# 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.

{{< tabs >}}
  {{< tab label="Pre-built package" >}}
  
  Pre-compiled packages are available for common platforms and provide the simplest installation method.
  
  > [!NOTE]+ Logging In
  > Pre-built packages require Plakar authentication. See [Logging in to Plakar](../../guides/logging-in-to-plakar) for details.
  
  Install the S3 package:
  
  ```bash
  $ plakar pkg add s3
  ```

  Verify installation:
  
  ```bash
  $ plakar pkg list
  ```
  
  {{< /tab >}}
  {{< tab label="Building from source" >}}
  
  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
  ```
  
  {{< /tab >}}
{{< /tabs >}}

To list, upgrade, or remove the package, see [managing packages guide](../../guides/managing-packages/).

## Configuration

### Addressing styles

S3-compatible services use one of two addressing styles for buckets.

**Path-style** (default) — the bucket name is part of the URL path:

```bash
s3://<S3_ENDPOINT>/<BUCKET_NAME>
```

**Virtual-hosted-style** — the bucket name is part of the hostname. Required by some services that do not support path-style access (such as AWS S3 in certain regions):

```bash
s3://<BUCKET_NAME>.<S3_ENDPOINT>
```

Set `virtual_host=true` when using virtual-hosted-style addressing.

### Configuration options

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

| Option                   | Required | Description |
| ------------------------ | -------- | ----------- |
| `location`               | Yes      | S3 endpoint and bucket. See [Addressing styles](#addressing-styles) above. |
| `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. |
| `virtual_host`           | No       | Use virtual-hosted-style addressing. Defaults to `false`. |
| `tls_insecure_no_verify` | No       | Skip TLS certificate verification. Defaults to `false`. See warning below. |

> [!WARNING]+ TLS Certificate Verification
> Setting `tls_insecure_no_verify=true` disables TLS certificate verification, leaving your connection open to man-in-the-middle attacks. Only use this in controlled environments with self-signed certificates on trusted networks. Never use it with AWS S3, public cloud storage, or any production data.

## Source connector

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

{{< mermaid >}}
flowchart LR

subgraph Source["S3 Bucket"]
  FS["Objects"]
end

subgraph Plakar["Plakar"]
  Connector["Retrieve objects via<br/>S3 API"]
  Transform["Encrypt & deduplicate"]
  Connector --> Transform
end

Source --> Connector

Store["Kloset Store"]
Transform --> Store
{{< /mermaid >}}

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.

{{< mermaid >}}
flowchart LR

subgraph Sources["Any Source"]
  FS["Data"]
end

subgraph Plakar["Plakar"]
  Transform["Encrypt & deduplicate"]
  Connector["Store via<br/>S3 API"]
  Transform --> Connector
end

Sources --> Transform

subgraph Storage["S3 Storage"]
  Store["Kloset Store"]
end

Connector --> Store
{{< /mermaid >}}

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.

{{< mermaid >}}
flowchart LR

Store["Kloset Store"]

subgraph Plakar["Plakar"]
  Transform["Decrypt & reconstruct"]
  Connector["Restore via<br/>S3 API"]
  Transform --> Connector
end

Store --> Transform

subgraph Destination["S3 Bucket"]
  FS["Objects"]
end

Connector --> Destination
{{< /mermaid >}}

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>
```