# S3 Backend - Seafile Admin Manual
Author: seafile

Skip to content

# Setup With S3 Storage

Deployment notes

- This feature is only for Pro Edition

- If your Seafile server is deployed from binary packages, you have to do the following steps before deploying:

  1. install `boto3` to your machine

         sudo pip install boto3

  2. Install and configure memcached or Redis.

     For best performance, Seafile requires enable memory cache for objects. We recommend to at least allocate 128MB memory for memcached or Redis.

     The configuration options differ for different S3 storage. We'll describe the configurations in separate sections. You also need to add memory cache configurations

New feature from 12.0 pro edition

If your will deploy Seafile server in Docker, you can modify the following fields in `.env` before starting the services:

    INIT_S3_STORAGE_BACKEND_CONFIG=true
    INIT_S3_COMMIT_BUCKET=<your-commit-objects>
    INIT_S3_FS_BUCKET=<your-fs-objects>
    INIT_S3_BLOCK_BUCKET=<your-block-objects>
    INIT_S3_KEY_ID=<your-key-id>
    INIT_S3_SECRET_KEY=<your-secret-key>
    INIT_S3_USE_V4_SIGNATURE=true
    INIT_S3_AWS_REGION=us-east-1 # your AWS Region
    INIT_S3_HOST= # your S3 Host (specify when not use AWS)
    INIT_S3_USE_HTTPS=true

The above modifications will generate the same configuration file as this manual and will take effect when the service is started for the first time.

## How to configure S3 in Seafile

Seafile configures S3 storage by adding or modifying the following section in `seafile.conf`:

    [xxx_object_backend]
    name = s3
    bucket = my-xxx-objects
    key_id = your-key-id
    key = your-secret-key
    use_v4_signature = true
    use_https = true
    ... ; other optional configurations

You have to create at least 3 buckets for Seafile, corresponding to the sections: `commit_object_backend`, `fs_object_backend` and `block_backend`. For the configurations for each backend section, please refer to the following table:

Variable | Description
--- | ---
`bucket` | Bucket name for commit, fs, and block objects. Make sure it follows S3 naming rules (you can refer the notes below the table).
`key_id` | The `key_id` is required to authenticate you to S3. You can find the `key_id` in the "security credentials" section on your AWS account page or from your storage provider.
`key` | The `key` is required to authenticate you to S3. You can find the `key` in the "security credentials" section on your AWS account page or from your storage provider.
`use_v4_signature` | There are two versions of authentication protocols that can be used with S3 storage: Version 2 (older, may still be supported by some regions) and Version 4 (current, used by most regions). If you don't set this option, Seafile will use the v2 protocol. It's suggested to use the v4 protocol.
`use_https` | Use https to connect to S3. It's recommended to use https.
`aws_region` | (Optional) If you use the v4 protocol and AWS S3, set this option to the region you chose when you create the buckets. If it's not set and you're using the v4 protocol, Seafile will use `us-east-1` as the default. This option will be ignored if you use the v2 protocol.
`host` | (Optional) The endpoint by which you access the storage service. Usually it starts with the region name. It's required to provide the host address if you use storage provider other than AWS, otherwise Seafile will use AWS's address (i.e., `s3.us-east-1.amazonaws.com`).
`sse_c_key` | (Optional) A string of 32 characters can be generated by `openssl rand -base64 24`. It can be any 32-character long random string. It's required to use V4 authentication protocol and https if you enable SSE-C.

`path_style_request`

(Optional) This option asks Seafile to use URLs like `https://192.168.1.123:8080/bucketname/object` to access objects. In Amazon S3, the default URL format is in virtual host style, such as `https://bucketname.s3.amazonaws.com/object`. But this style relies on advanced DNS server setup. So most self-hosted storage systems only implement the path style format. So we recommend to set this option to true for self-hosted storage.

Bucket naming conventions

No matter if you using AWS or any other S3 compatible object storage, we recommend that you follow S3 naming rules. When you create buckets on S3, please read the S3 rules for naming first. Note, especially do not use capital letters in the name of the bucket (do not use camel-style naming, such as MyCommitObjects).

Good naming of a bucketBad naming of a bucket

- seafile-commit-object
- seafile-fs-object
- seafile-block-object

- SeafileCommitObject
- seafileFSObject
- seafile block object

### Use server-side encryption with customer-provided keys (SSE-C) in Seafile

Since Pro 11.0, you can use SSE-C to S3. Add the following `sse_c_key` to seafile.conf (as shown in the above variables table):

    [commit_object_backend]
    name = s3
    ......
    use_v4_signature = true
    use_https = true
    sse_c_key = XiqMSf3x5ja4LRibBbV0sVntVpdHXl3P

    [fs_object_backend]
    name = s3
    ......
    use_v4_signature = true
    use_https = true
    sse_c_key = XiqMSf3x5ja4LRibBbV0sVntVpdHXl3P

    [block_backend]
    name = s3
    ......
    use_v4_signature = true
    use_https = true
    sse_c_key = XiqMSf3x5ja4LRibBbV0sVntVpdHXl3P

`sse_c_key` is a string of 32 characters.

You can generate sse_c_key with the following command. Note that the key doesn't have to be base64 encoded. It can be any 32-character long random string. The example just show one possible way to generate such a key.

    openssl rand -base64 24

Warning

If you have existing data in your S3 storage bucket, turning on the above configuration will make your data inaccessible. That's because Seafile server doesn't support encrypted and non-encrypted objects mixed in the same bucket. You have to create a new bucket, and migrate your data to it by following storage backend migration documentation.

## Example

AWSExoscaleHetznerOther Public Hosted S3 StorageSelf-hosted S3 Storage

    [commit_object_backend]
    name = s3
    bucket = my-commit-objects
    key_id = your-key-id
    key = your-secret-key
    use_v4_signature = true
    aws_region = eu-central-1
    use_https = true

    [fs_object_backend]
    name = s3
    bucket = my-fs-objects
    key_id = your-key-id
    key = your-secret-key
    use_v4_signature = true
    aws_region = eu-central-1
    use_https = true

    [block_backend]
    name = s3
    bucket = my-block-objects
    key_id = your-key-id
    key = your-secret-key
    use_v4_signature = true
    aws_region = eu-central-1
    use_https = true

    [commit_object_backend]
    name = s3
    bucket = your-bucket-name
    host = sos-de-fra-1.exo.io
    key_id = ...
    key = ...
    use_https = true
    path_style_request = true

    [fs_object_backend]
    name = s3
    bucket = your-bucket-name
    host = sos-de-fra-1.exo.io
    key_id = ...
    key = ...
    use_https = true
    path_style_request = true

    [block_backend]
    name = s3
    bucket = your-bucket-name
    host = sos-de-fra-1.exo.io
    key_id = ...
    key = ...
    use_https = true
    path_style_request = true

    [commit_object_backend]
    name = s3
    bucket = your-bucket-name
    host = fsn1.your-objectstorage.com
    key_id = ...
    key = ...
    use_https = true
    path_style_request = true

    [fs_object_backend]
    name = s3
    bucket = your-bucket-name
    host = fsn1.your-objectstorage.com
    key_id = ...
    key = ...
    use_https = true
    path_style_request = true

    [block_backend]
    name = s3
    bucket = your-bucket-name
    host = fsn1.your-objectstorage.com
    key_id = ...
    key = ...
    use_https = true
    path_style_request = true

There are other S3-compatible cloud storage providers in the market, such as Blackblaze and Wasabi. Configuration for those providers are just a bit different from AWS. We don't assure the following configuration works for all providers. If you have problems please contact our support

    [commit_object_backend]
    name = s3
    bucket = my-commit-objects
    host = <access endpoint for storage provider>
    key_id = your-key-id
    key = your-secret-key
    # v2 authentication protocol will be used if not set
    use_v4_signature = true
    # required for v4 protocol. ignored for v2 protocol.
    aws_region = <region name for storage provider>
    use_https = true

    [fs_object_backend]
    name = s3
    bucket = my-fs-objects
    host = <access endpoint for storage provider>
    key_id = your-key-id
    key = your-secret-key
    use_v4_signature = true
    aws_region = <region name for storage provider>
    use_https = true

    [block_backend]
    name = s3
    bucket = my-block-objects
    host = <access endpoint for storage provider>
    key_id = your-key-id
    key = your-secret-key
    use_v4_signature = true
    aws_region = <region name for storage provider>
    use_https = true

Many self-hosted object storage systems are now compatible with the S3 API, such as OpenStack Swift, Ceph's RADOS Gateway and Minio. You can use these S3-compatible storage systems as backend for Seafile. Here is an example config:

    [commit_object_backend]
    name = s3
    bucket = my-commit-objects
    key_id = your-key-id
    key = your-secret-key
    host = <your s3 api endpoint host>:<your s3 api endpoint port>
    path_style_request = true
    use_v4_signature = true
    use_https = true

    [fs_object_backend]
    name = s3
    bucket = my-fs-objects
    key_id = your-key-id
    key = your-secret-key
    host = <your s3 api endpoint host>:<your s3 api endpoint port>
    path_style_request = true
    use_v4_signature = true
    use_https = true

    [block_backend]
    name = s3
    bucket = my-block-objects
    key_id = your-key-id
    key = your-secret-key
    host = <your s3 api endpoint host>:<your s3 api endpoint port>
    path_style_request = true
    use_v4_signature = true
    use_https = true

## Run and Test

Now you can start Seafile and test