# S3

The **S3 integration** enables backup and restoration of S3 buckets through S3-compatible APIs. All bucket contents including objects, metadata, and folder hierarchies are captured and stored in a Kloset store with encryption and deduplication.

The S3 integration provides three connectors:

| Connector type         | Description                                           |
|------------------------|------------------------------------------------------|
| **Source connector**   | Back up S3 buckets into a Kloset store.             |
| **Storage connector**  | Use S3-compatible storage as a Kloset store backend.|
| **Destination connector** | Restore bucket contents from a Kloset store back to S3. |

## Installation

The S3 package can be installed using pre-built binaries or compiled from source.

### Pre-built package

Pre-compiled packages are available for common platforms and provide the simplest installation method.

Install the S3 package:

```bash
$ plakar pkg add s3
```

Verify installation:

```bash
$ plakar pkg list
```

### Source builds

Source builds are useful when pre-built packages are unavailable or when customization is required.

**Prerequisites:**

- Go toolchain compatible with your **Plakar** version

Build the package:

```bash
$ plakar pkg build s3
```

A package archive will be created in the current directory (e.g., `s3_v1.0.0_darwin_arm64.ptar`).

Install the package:

```bash
$ plakar pkg add ./s3_v1.0.0_darwin_arm64.ptar
```

Verify installation:

```bash
$ plakar pkg list
```

To list, upgrade, or remove the package, see the [managing packages guide](/content/docs/v1.0.6/guides/managing-packages/index.html).

## Configuration

### Configuration options

These options apply to all three connectors (source, storage, destination).

| Option                  | Required | Description                                                                               |
|-------------------------|----------|-------------------------------------------------------------------------------------------|
| `location`              | Yes      | S3 endpoint and bucket including region (format: `s3://s3.region.amazonaws.com/bucket`) |
| `access_key`            | Yes      | S3 Access Key ID.                                                                       |
| `secret_access_key`     | Yes      | S3 Secret Access Key.                                                                    |
| `passphrase`            | No       | Encryption passphrase. If not set, Plakar will prompt interactively. Source connector only. |
| `use_tls`               | No       | Enable TLS. Recommended for all internet-facing connections.                             |

## Source connector

The source connector retrieves objects from S3 buckets and stores them in a Kloset store with encryption and deduplication.

```
Plakar

S3 Bucket

Objects

Retrieve objects via
S3 API

Encrypt & deduplicate

Kloset Store
```

Register the source and run a backup:

```bash
$ plakar source add my-s3-bucket \
  location=s3://<S3_ENDPOINT>/<BUCKET_NAME> \
  access_key=<YOUR_ACCESS_KEY_ID> \
  secret_access_key=<YOUR_SECRET_ACCESS_KEY> \
  use_tls=true

$ plakar at /var/backups backup "@my-s3-bucket"
```

## Storage connector

The storage connector uses S3-compatible storage as the backend for a Kloset store. All Plakar data—snapshots, chunks, metadata—is stored as S3 objects.

```
S3 Storage

Plakar

Any Source

Data

Encrypt & deduplicate

Store via
S3 API

Kloset Store
```

Register the store, initialize it, and run a backup:

```bash
$ plakar store add my-s3-store \
  location=s3://<S3_ENDPOINT>/<BUCKET_NAME> \
  access_key=<YOUR_ACCESS_KEY_ID> \
  secret_access_key=<YOUR_SECRET_ACCESS_KEY> \
  use_tls=true

$ plakar at "@my-s3-store" create
$ plakar at "@my-s3-store" backup /var/www
```

## Destination connector

Restores objects from a Kloset store back to an S3 bucket.

```
Plakar

S3 Bucket

Objects

Kloset Store

Decrypt & reconstruct

Restore via
S3 API
```

Register the destination and restore a snapshot:

```bash
$ plakar destination add my-s3-restore \
  location=s3://<S3_ENDPOINT>/<BUCKET_NAME> \
  access_key=<YOUR_ACCESS_KEY_ID> \
  secret_access_key=<YOUR_SECRET_ACCESS_KEY> \
  use_tls=true

$ plakar at /var/backups restore -to "@my-s3-restore" <snapshot_id>
```