Configure Cloud Storage for Backup & Restore

1

Create the S3 bucket

The connection test checks that the bucket already exists. Create it in AWS first (do not rely on Quemsi to create it).

1. Sign in to the AWS S3 console.
2. Choose Create bucket.
3. Bucket name — globally unique, 3–63 characters, lowercase letters, numbers, and hyphens only (for example acme-quemsi-backups). Copy this name; you will enter it in Quemsi.
4. AWS Region — pick the region closest to your agents (for example eu-west-1 or us-east-1). Copy the region code; it must match the Quemsi Region field exactly.
5. Object Ownership — leave ACLs disabled (recommended).
6. Block Public Access — leave all four settings on.
7. Bucket Versioning — optional. Quemsi versions packages in object keys; S3 versioning is not required.
8. Default encryption — prefer SSE-S3 (Amazon S3 managed keys). SSE-KMS works, but then the IAM user also needs KMS permissions (see below).
9. Choose Create bucket.

Do not add a bucket policy that grants s3:GetObject to *. Access should come only from the IAM user you create next.

2

Create a dedicated IAM user

1. Open the IAM Users page.
2. Choose Create user.
3. User name — for example quemsi-s3.
4. Leave Provide user access to the AWS Management Console unchecked. This user is for programmatic access from the Quemsi agent only.
5. Choose Next, skip attaching policies for now, then Create user.

3

Attach a least-privilege policy

Quemsi needs to check the bucket, upload backups, download restores, and delete objects when retention runs. Attach an inline policy on the user (IAM → Users → quemsi-s3 → Add permissions → Create inline policy → JSON).

Replace YOUR-BUCKET-NAME and YOUR-STORAGE-ROOT with the bucket name from step 1 and the prefix you will use in Quemsi (for example quemsi):

What each permission is for:

• s3:ListBucket — required for the Quemsi Test connection check (HeadBucket) and for the agent to confirm the bucket is reachable.
• s3:GetBucketLocation — lets the client confirm the bucket region.
• s3:PutObject — upload backup packages.
• s3:GetObject — download packages during restore.
• s3:DeleteObject — remove old packages when retention is enabled.

Save the policy (for example name it quemsi-s3-access).

4

Create access keys

1. Open the IAM user → Security credentials.
2. Under Access keys, choose Create access key.
3. Select Application running outside AWS (the Quemsi agent runs on your hosts, not as an AWS role).
4. Create the key, then copy both values immediately:
   • Access key ID — typically starts with AKIA
   • Secret access key — shown only once
5. Store the secret in a password manager. You cannot retrieve it again from AWS; if you lose it, create a new access key and deactivate the old one.

5

Confirm the agent can reach S3

The agent—not the Quemsi SaaS control plane—opens the S3 connection. Every host that will backup or restore must be able to reach AWS:

• Outbound HTTPS (TCP 443) to s3.<region>.amazonaws.com and *.s3.<region>.amazonaws.com (and s3.amazonaws.com for some global endpoints).
• If the agent runs in a private VPC with no internet, add an S3 Gateway VPC endpoint in that region, or a NAT gateway.
• If a corporate proxy inspects TLS, the agent must trust the corporate CA. See Corporate SSL / agent trust.

6

Optional: put keys in the agent environment

You can paste the keys into the Quemsi form, or keep them only on the agent host. Environment variables are better for production: the console stores variable names, and each agent resolves the secrets locally.

Set both variables on every agent that will use this drive (backup and restore environments):

Docker / Compose — add them under environment (or an env file that is not committed):

Linux systemd — add Environment= lines to the unit (or a drop-in), then sudo systemctl daemon-reload && sudo systemctl restart quemsi-agent.

Windows — set them as machine or user environment variables (System Properties → Environment Variables), then restart the agent. Test connection reads the process environment, not Java -D flags.

After the variables exist on the agent, enable Use environment variable in the Quemsi form (next section) and enter the names AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY instead of the raw keys.

7

Open AWS S3 Drives

In the Quemsi console, go to Company Setup → AWS S3 Drives, then click Add AWS S3 Drive.

Direct path: /setup/awss3drives/add

Make sure an agent shows as online before you test. The test is sent to that agent.

8

Fill in the drive fields

Match the labels in the form to the AWS values you created:

• Name* — URL-friendly id (A-Z, a-z, 0-9, -, _), for example company-s3. Immutable after create.
• Title* — Display name shown in the UI.
• Storage Root* — Key prefix inside the bucket (for example quemsi). Must match YOUR-STORAGE-ROOT in the IAM policy. Quemsi writes objects under {Storage Root}/{Root Path}/….
• Capacity* — Soft limit in the UI, e.g. 10 GB or 500 MB.
• Access Key* — AWS Access Key ID (starts with AKIA), or the env var name if the checkbox is enabled.
• Secret Key* — AWS Secret Access Key, or the env var name if the checkbox is enabled.
• Region* — the bucket region code from step 1, e.g. us-east-1, eu-west-1. Wrong region causes redirect or access errors.
• Bucket Name* — exact bucket name from step 1 (not an ARN, not a URL).

9

Test connection, then Save

Click the connection icon (Test connection) with an online agent selected. Quemsi asks that agent to call HeadBucket on your bucket with the keys you entered. A success toast means the agent can authenticate and see the bucket.

When the test succeeds, click Save. Agents receive the updated company model so the drive is available when you create a Storage.

1

Create the storage account

1. Sign in to the Azure portal and choose Create a resource → Storage account (or Create on the Storage accounts page).
2. Subscription and Resource group — pick yours, or create a group such as quemsi.
3. Storage account name — globally unique, 3–24 characters, lowercase letters and numbers only (no hyphens). Example: acmequemsibackups. Copy this name; it is the Quemsi Account Name.
4. Region — closest to your agents. Quemsi does not ask for a region field; the agent always uses https://{account}.blob.core.windows.net.
5. Primary service / Preferred storage type — required on the Basics tab (the portal shows “Preferred storage type is required” if you leave it empty). Choose Azure Blob Storage or Azure Data Lake Storage Gen 2 (wording may be Blob storage or Azure Data Lake Storage (ADLS) Gen 2). Do not pick Azure Files, Tables, or Queues. This only steers the create wizard; it does not lock the account to one service.
6. Performance — Standard is enough for backups.
7. Redundancy — LRS is fine for a dedicated backup account; GRS if you want geo-redundant copies in Azure as well.
8. On Advanced (or equivalent):
   • Leave Allow storage account key access Enabled. Quemsi authenticates with the account key; if you disable shared-key access, the connection test fails.
   • Set Allow Blob anonymous access (public access) to Disabled.
   • Leave Hierarchical namespace (Data Lake Gen2) off unless you already require it. Standard Blob storage is what Quemsi uses.
   • Minimum TLS 1.2 is the default and is compatible.
9. On Networking, choose how the agent will reach the account (next step), then create the account and wait until deployment finishes.

2

Allow the agent to reach Blob Storage

The agent—not the Quemsi SaaS control plane—opens the Blob connection. Every host that will back up or restore must reach https://{account}.blob.core.windows.net on HTTPS (TCP 443).

• Public network access: Enabled from all networks — simplest. Use this unless your security policy requires a firewall.
• Enabled from selected virtual networks and IP addresses — add the public IP of each agent host (or the NAT gateway they egress through). Missing IPs show up as timeouts, not always as a clear “firewall” message.
• Private endpoint — works if the agent is in a VNet that can resolve {account}.blob.core.windows.net to the private IP (usually via the Azure private DNS zone privatelink.blob.core.windows.net).
• If a corporate proxy inspects TLS, the agent must trust the corporate CA. See Corporate SSL / agent trust.

3

Copy the account name and an access key

1. Open the storage account → Security + networking → Access keys.
2. Confirm the Storage account name matches what you will enter in Quemsi.
3. Choose Show next to key1 (or key2) and copy the Key value—not the connection string.
4. Store the key in a password manager. You can regenerate a key later; if you do, update Quemsi (or the agent env var) before the old key stops working.

Prefer rotating with two keys: put the new key into Quemsi first, then regenerate the unused key in Azure.

4

Choose the blob container name

In Quemsi, drive Storage Root is the container name, not a folder path. Azure container names are 3–63 characters, lowercase letters, numbers, and hyphens, and must start and end with a letter or number (for example quemsi-backups). Do not use underscores, uppercase, or nested paths such as backups/prod.

You can create the container now (Storage account → Data storage → Containers → + Container, anonymous access Private), or leave it for Quemsi. On first backup the agent calls create-container; if the name already exists, that is fine. The Test connection check only lists containers on the account—it does not require this container to exist yet.

Folders inside the container are set later as the Storage Root Path (for example prod-snapshots).

5

Optional: put the account key in the agent environment

You can paste the key into the Quemsi form, or keep it only on the agent host. Environment variables are better for production: the console stores the variable name, and each agent resolves the secret locally. Account Name is never an env var—it stays the real storage account name.

Set the variable on every agent that will use this drive (backup and restore environments):

Docker / Compose — add it under environment (or an env file that is not committed):

Linux systemd — add an Environment= line to the unit (or a drop-in), then sudo systemctl daemon-reload && sudo systemctl restart quemsi-agent.

Windows — set it as a machine or user environment variable (System Properties → Environment Variables), then restart the agent. Test connection reads the process environment, not Java -D flags.

After the variable exists on the agent, enable Use environment variable in the Quemsi form (next section) and enter the name AZURE_STORAGE_KEY in Account Key.

6

Open Azure Blob Drives

In the Quemsi console, go to Company Setup → Azure Blob Drives, then click Add Azure Blob Drive.

Direct path: /setup/azureblobdrives/add

Make sure an agent shows as online before you test. The test is sent to that agent.

7

Fill in the drive fields

Match the labels in the form to the Azure values you created:

• Name* — URL-friendly id (A-Z, a-z, 0-9, -, _), for example company-azure. Immutable after create.
• Title* — Display name shown in the UI.
• Storage Root* — the blob container name from step 4 (for example quemsi-backups). Not a nested path. Quemsi creates this container on first backup if it is missing.
• Capacity* — Soft limit in the UI, e.g. 10 GB or 500 MB.
• Account Name* — exact storage account name from step 1 (lowercase, no hyphens). Always the real name, even when the env-var checkbox is on. Quemsi builds https://{account}.blob.core.windows.net.
• Account Key* — the key from Access keys, or the env var name if the checkbox is enabled.

8

Test connection, then Save

Click the connection icon (Test connection) with an online agent selected. Quemsi asks that agent to list containers on the account with the name and key you entered. A success toast means the agent can authenticate and reach Blob Storage.

When the test succeeds, click Save. Agents receive the updated company model so the drive is available when you create a Storage.

1

Open Storages

Go to Agent Setup → Storages, then click Add Storage.

Direct path: /setup/storages/add

You can also create a drive from the Storage form via the + next to Drive; Quemsi returns you to the Storage form afterward.

2

Configure the Storage

• Name* / Title* — Id and display name for the storage (flows reference the name).
• Type* — Choose AWS S3 Storage or Azure Blob Storage.
• Drive* — Select the drive you created above.
• Root Path* — Path under the drive with no leading or trailing slash (for example prod-snapshots or shared/uat). On S3 this is the key prefix under Storage Root; on Azure it is the blob folder inside the container.
• Retention* — noretention or default.
• Size Limit* — e.g. 5 GB (required in the form; needed when retention is enabled).

3

Save

Click Save. Agents receive the updated model so the Storage is available in flow builders.

1

Backup to cloud

In a backup (or snapshot) flow, set the destination to your Storage. The agent uploads versioned packages to S3 or Azure Blob using the drive credentials.

2

Restore from cloud

In a restore flow, use a Stored Data source that points at the same Storage name. An agent in another environment downloads the packages and restores into its local datasource.

Access Denied / 403

• The IAM policy is missing s3:ListBucket on the bucket ARN (needed for Test connection).
• Object actions are scoped to a prefix that does not match Storage Root (for example policy uses quemsi/* but the form has backups).
• Bucket name is wrong (typo, or you pasted an ARN / URL instead of the name).
• The bucket uses SSE-KMS and the user cannot call kms:Decrypt / kms:GenerateDataKey on that key.
• An SCP, permission boundary, or bucket policy is denying the user even though the inline policy looks correct.

NoSuchBucket / 404 / bucket does not exist

• Create the bucket before testing. Test connection does not create it.
• Region in Quemsi does not match the bucket’s region. Use the region code (for example eu-central-1), not the display name.
• You entered an account ID, ARN, or s3://… URI in Bucket Name. Use only the bucket name.

environment-vars-not-set

You enabled Use environment variable, but the agent process does not have both named variables. Confirm the names in the form match the names on the host, then restart the agent after changing environment variables. Docker Compose and systemd only pick up new env values after a recreate/restart.

Timeout or unable to reach S3

• No agent is online, or you tested against the wrong agent.
• The agent host cannot open HTTPS to S3 (firewall, missing NAT, or no VPC endpoint).
• TLS inspection is breaking the AWS SDK. Import the corporate CA as in Corporate SSL / agent trust.

SignatureDoesNotMatch / invalid credentials

• Secret access key was copied with a missing character or extra space.
• Access key was deactivated or belongs to a different user than the policy.
• The agent clock is badly skewed (S3 signatures are time-sensitive). Sync NTP on the agent host.

unable-to-create-s3-bucket / not authorized to perform s3:CreateBucket

The bucket you created is fine. Older agents called CreateBucket on every flow start; AWS returns 403 when that action is missing even if the bucket already exists. Current agents skip create when HeadBucket succeeds, so the least-privilege policy in this tutorial is enough. Restart the updated agent. If you cannot upgrade yet, add s3:CreateBucket on arn:aws:s3:::YOUR-BUCKET-NAME temporarily.

Test succeeds, backup or restore fails

• Policy allows ListBucket but not s3:PutObject (backup) or s3:GetObject (restore).
• Retention fails without s3:DeleteObject.
• The Storage Root Path plus drive Storage Root produce keys outside the IAM prefix.

Object keys look like {Storage Root}/{Root Path}/{data name}/{versioned file}. The IAM Resource must cover that prefix.

AuthenticationFailed / 403 / Authorization error

• Allow storage account key access is disabled on the account. Re-enable shared-key access; Quemsi cannot use Entra ID or SAS.
• You pasted a connection string or SAS token into Account Key. Use the key from Access keys only.
• The key was regenerated in Azure but Quemsi still has the old value (or the agent env var was not updated and the agent not restarted).
• Account Name does not match the account that issued the key (typo, or a different account in another subscription).

Timeout or unable to reach Azure Blob

• No agent is online, or you tested against the wrong agent.
• Storage firewall is set to selected networks/IPs and the agent’s egress IP is not allowed.
• Private endpoint is configured but the agent still resolves public DNS (or the opposite: public access is disabled and there is no private path).
• TLS inspection is breaking the Azure SDK. Import the corporate CA as in Corporate SSL / agent trust.

Account not found / DNS / unknown host

• Account Name is wrong, includes hyphens, or was entered as a URL (https://…) or resource ID. Use only the 3–24 character account name.
• The account lives in Azure Government or Azure China. Quemsi always uses *.blob.core.windows.net.

environment-vars-not-set

You enabled Use environment variable, but the agent process does not have that named variable. Confirm the name in Account Key matches the name on the host, then restart the agent. Docker Compose and systemd only pick up new env values after a recreate/restart. Account Name must still be the real account name, not an env var.

Test succeeds, backup or restore fails

• Storage Root is not a valid container name (uppercase, underscores, slashes). Azure rejects names such as backups/prod or Quemsi_Backups.
• A resource lock, immutability policy, or legal hold on the container blocks create, overwrite, or delete.
• The account is full or a management lock prevents creating the container on first backup.

Blobs are stored as {Root Path}/{data name}/{versioned file} inside the container named by Storage Root.