# S3 Transfers

Perform verified file transfers directly to an S3 bucket using OffShoot.

{% hint style="info" %}
Currently, you can only set S3 disks as a Destination.
{% endhint %}

{% hint style="info" %}
This feature requires an OffShoot Pro license. Upgrade via the [License Manager](https://account.hedge.video), or via OffShoot > Settings > License. Check out all Pro features [here](https://hedge.video/offshoot/pro-features).
{% endhint %}

## Requirements

* OffShoot 23.2 or newer
* A Pro License
* Access to an S3 bucket with at least `write`, `delete` and `listBucket` permissions

## How to use

1. Go to `Settings > Cloud`.
2. Choose an S3 provider from the list or [`Generic S3`](#generic-s3).
3. Click  `Add...` to create a new S3 connection.

<figure><img src="https://1060439511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LStRji2w1AYja1bLBFv%2Fuploads%2F2Dyo1D5QnnLBoh0y9K7o%2Fimage.png?alt=media&#x26;token=ff4dcd2e-634c-4b0c-917c-a94ecc4c8417" alt=""><figcaption></figcaption></figure>

4. Enter your S3 credentials – the `Address`, `Bucket Name`, `Access Key`, and `Secret`.

{% hint style="info" %}
The AWS S3 address is constructed as follows: `https://s3.` followed by `<bucket region>`, and ending with `.amazonaws.com`.
{% endhint %}

<figure><img src="https://1060439511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LStRji2w1AYja1bLBFv%2Fuploads%2FY9SBs9HyMgEsmQ1MRg8N%2Fimage.png?alt=media&#x26;token=cf8a555f-6cae-4026-ac33-086dffc865ba" alt=""><figcaption></figcaption></figure>

5. Click `Connect`.
6. The S3 bucket will now be available as a Disk in OffShoot.

{% hint style="info" %}
On Mac, if you encounter an ‘Could not create S3 connection’ error, hover over the error message for more details. If you need further assistance, contact us at <offshoot@hedge.video>.
{% endhint %}

## AWS S3 Transfer acceleration

AWS S3 buckets with [Transfer Acceleration](https://aws.amazon.com/s3/transfer-acceleration/) are supported in OffShoot 24.1 and newer.

<figure><img src="https://1060439511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LStRji2w1AYja1bLBFv%2Fuploads%2FxRRcQC9VYTqdkQKvtwYT%2Fimage.png?alt=media&#x26;token=c2c39000-f895-4eae-a6a3-e0b468bf0746" alt=""><figcaption></figcaption></figure>

## Encryption

OffShoot supports S3 buckets encrypted with:

* Amazon S3 managed keys (SSE-S3)
* AWS Key Management Service keys (SSE-KMS and DSSE-KMS)

## Configuring a S3 connection

### Connecting to a path

You can also define an `Optional Path` as part of your S3 bucket's `Location`, which OffShoot will mount as your S3 bucket's "root point".

<figure><img src="https://1060439511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LStRji2w1AYja1bLBFv%2Fuploads%2Fgepk6qCRj5J5lFBzQNCv%2Fimage.png?alt=media&#x26;token=6bbf16f7-b8ee-4dc8-9e8c-88508d1c8794" alt="" width="563"><figcaption></figcaption></figure>

<figure><img src="https://1060439511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LStRji2w1AYja1bLBFv%2Fuploads%2F67MoHGltxtzvVKkgpWn9%2Fimage.png?alt=media&#x26;token=137b63bc-613d-4e30-9371-6d85e3ab64c6" alt="" width="473"><figcaption></figcaption></figure>

{% hint style="info" %}
Hover over the disk with your mouse in OffShoot, and OffShoot will display the `Bucket name` and `Optional Path` as a tooltip.
{% endhint %}

### Using a Label

By default, OffShoot uses the `Bucket name` as the disk name. As with other disks in OffShoot, you can rename it with a `Label` when creating or configuring the connection.

<figure><img src="https://1060439511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LStRji2w1AYja1bLBFv%2Fuploads%2FJD3VxjgNxSimX9TuPIhb%2Fimage.png?alt=media&#x26;token=6f497b37-9550-42cf-8983-48ecb325d4c3" alt="" width="563"><figcaption></figcaption></figure>

<figure><img src="https://1060439511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LStRji2w1AYja1bLBFv%2Fuploads%2FDe0OsOqomxA0vbKGEgzo%2Fimage.png?alt=media&#x26;token=eb9d71a6-d863-4012-9f4a-a631be47c608" alt="" width="527"><figcaption></figcaption></figure>

### Configuring an S3 connection via CLI (macOS only)

It's possible to create a connection via the command line. [Learn more](https://docs.hedge.video/offshoot/features/s3-transfers/configuring-connections).&#x20;

## Browsing a Bucket

Once your S3 bucket is connected, you can browse it in OffShoot by:

* Double-clicking the S3 bucket's disk icon.
* Choosing `Browse...` from the Disk's menu.

<figure><img src="https://1060439511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LStRji2w1AYja1bLBFv%2Fuploads%2FzuPL100nTtfehbtNmmgc%2Fimage.png?alt=media&#x26;token=1f5bc10a-2108-463e-86d8-01fd33674030" alt="" width="329"><figcaption></figcaption></figure>

## Editing & Removing a Connection

You can edit or remove an existing S3 connection by:

* Double-clicking the connection.
* Clicking the ellipses `⋯`, then choosing `Edit` or `Remove.`

<figure><img src="https://1060439511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LStRji2w1AYja1bLBFv%2Fuploads%2FUkIG6khPSg7fsah6ABlH%2Fimage.png?alt=media&#x26;token=8d087ba7-bd0b-48e2-a449-e65793cd73e8" alt=""><figcaption></figcaption></figure>

## Setting a Destination Folder

It's possible to set a Destination folder via `Disk menu` > `Destination Folder` > `Browse...`&#x20;

<figure><img src="https://1060439511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LStRji2w1AYja1bLBFv%2Fuploads%2FwoPjzKBBDonDcyC2ZxAf%2Fimage.png?alt=media&#x26;token=745b3ecb-dc69-4fc2-b620-b2a6d350912b" alt="" width="563"><figcaption></figcaption></figure>

New folder creation is also possible, but OffShoot only creates those at transfer time.

## Verification

S3 transfers are always verified using multi-part MD5 checksums. This is done server-side and does not require a readback of the files or Destination verification to be turned ON.

## Concurrency

OffShoot uploads multiple files (in parts) to S3 at the same time. To adjust these settings, you can modify the following defaults:

{% tabs %}
{% tab title="macOS" %}

<pre><code><strong>multi-part// sets the multi-part size in MB; default = 64 (min 5 MB, max 5GB)
</strong>defaults write nl.syncfactory.Hedge.Mac "S3MultipartSize" -int &#x3C;size in MB>

// sets the maximum amount of parts uploaded simultaneously; default = 10
defaults write nl.syncfactory.Hedge.Mac "S3MultipartConcurrencyLimit" -int &#x3C;amount in parts>

// delete these keys if you want the reset to the default values
defaults delete nl.syncfactory.Hedge.Mac "S3MultipartSize"
defaults delete nl.syncfactory.Hedge.Mac "S3MultipartConcurrencyLimit"
</code></pre>

{% endtab %}

{% tab title="Windows" %}

```
Location - Computer\HKEY_CURRENT_USER\Software\Hedge
Key - CloudIntegrationConcurrency and CloudIntegrationPartSize
Type - DWORD (Hex)

CloudIntegrationConcurrency // maximum amount of parts uploaded simultaneously, default = 10
CloudIntegrationPartSize // multi-part size in bytes, default = 15728640 (min 5MiB, max 5GiB)
```

{% endtab %}
{% endtabs %}

## API

To set an S3 bucket with the API, use the [`setDestination`](https://docs.hedge.video/offshoot/automation/api#set-destination) call with `Bucket Name` and `Optional Path` as the `path` parameter's value:

```
offshoot://setDestination?path=hedge-s3-test
```

## Limitations

* Setting an S3 bucket as a `Source` is currently unsupported.
* Transfers will use the `Standard` storage class.&#x20;
* Local S3 connections using self-signed certificates are currently unsupported.
* Due to S3 limitations, OffShoot cannot transfer:
  * Empty folders
  * File aliases/symlinks
  * Zero byte files
  * Files larger than 5TiB
* Due to S3 limitations, the FoolCat, EditReady, and iconik integrations are unsupported.

{% hint style="success" %}
OffShoot logs any files or folders that couldn't be transferred in the [Transfer Logs](https://docs.hedge.video/offshoot/logging#transfer-logs).
{% endhint %}

## Certified S3 Providers

Not all S3 providers have full S3 support for features like verification and multipart uploads. We actively test and certify S3 vendors often used for media production workflows. Certified S3 providers are available in OffShoot through their own S3 panel:&#x20;

* Amove
* AWS
* Backblaze B2
* Perifery
* Seagate Lyve
* Storj
* Symply Nebula
* Wasabi

## Generic S3

We obviously are not able to test all available S3 providers, so if you have a different (thus non-certified) S3 provider, simply try the `Generic S3` integration. If successful, please let us know. Also, feel free to loop us in when you run into issues.&#x20;

{% hint style="info" %}
Are you an S3 vendor and looking for certification? Reach out: <offshoot@hedge.video>
{% endhint %}