MinIO destination

Walwarden supports MinIO as a backup destination via the S3-compatible API. This page covers creating and configuring the bucket and the access key walwarden uses to write backups.

Walwarden supports the following parameters for this provider:

Trust boundary note. Walwarden stores the access key for this destination. Unlike the AWS BYO S3 path (which uses short-lived AssumeRole session credentials), this key is long-lived. Use a minimum-scope key (see step 3 below) and rotate it periodically. Revoke the key immediately if walwarden is ever compromised.

Preflight status. MinIO destinations start in unverified state. Run preflight after registration so walwarden can verify the access key, bucket access, Object Lock, versioning, public-access posture, encryption behavior, and retention writes.

Step 1: Create the bucket with Object Lock enabled

Object Lock in MinIO must be enabled at bucket creation. You cannot enable it on an existing bucket.

Using the MinIO client (mc):

mc mb --with-lock minio-alias/walwarden-backups

Using the MinIO console:

1. Go to Buckets and click Create bucket.
2. Enter a bucket name.
3. Toggle Object Locking on.
4. Click Create bucket.

Set the default retention mode to GOVERNANCE with a period that matches or exceeds your retentionFloorDays setting in walwarden:

mc retention set --default GOVERNANCE 30d minio-alias/walwarden-backups

Step 2: Block public access

MinIO buckets are private by default. Confirm no public access policy has been applied to the bucket. Walwarden's preflight verifies the public-access posture it can observe through the S3-compatible API.

Step 3: Create a minimum-scope user and access key

Create a user and policy that grants walwarden only the permissions it needs. Walwarden requires PutObject, GetObject, HeadObject, DeleteObject, ListBucket, GetBucketLocation, GetObjectRetention, and PutObjectRetention on the specific bucket.

Create a policy file:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:HeadObject",
        "s3:DeleteObject",
        "s3:ListBucket",
        "s3:GetBucketLocation",
        "s3:GetObjectRetention",
        "s3:PutObjectRetention",
        "s3:GetObjectLegalHold",
        "s3:PutObjectLegalHold",
        "s3:GetBucketVersioning",
        "s3:ListBucketMultipartUploads",
        "s3:ListMultipartUploadParts",
        "s3:AbortMultipartUpload"
      ],
      "Resource": [
        "arn:aws:s3:::walwarden-backups",
        "arn:aws:s3:::walwarden-backups/*"
      ]
    }
  ]
}

Apply the policy and create the user:

mc admin policy create minio-alias walwarden-policy /path/to/policy.json
mc admin user create minio-alias walwarden-user <strong-secret>
mc admin policy attach minio-alias walwarden-policy --user walwarden-user

Generate an access key for the user and note the access key ID and secret access key.

Step 4: Register the destination in walwarden

1. In the walwarden dashboard, go to Destinations > Add destination.
2. Select MinIO (S3-compatible) as the provider.
3. Fill in:
   • Endpoint URL — the HTTPS URL of your MinIO instance (for example, https://minio.your-domain.com).
   • Bucket name — the bucket name from step 1.
   • Region — us-east-1 or whatever region string your MinIO cluster uses.
   • Access key ID — from step 3.
   • Secret access key — from step 3.
4. Click Save.

The destination will appear in state unverified. Run preflight from the destination detail page before attaching it to scheduled backups.

Common footguns

Object Lock not enabled at bucket creation

MinIO does not allow enabling Object Lock on an existing bucket. If you skipped the --with-lock flag, you must delete the bucket and re-create it with Object Lock enabled. There is no in-place migration path.

HTTP endpoint instead of HTTPS

Walwarden refuses to connect to endpoints that accept plain HTTP. Make sure the endpoint URL you paste starts with https://. If your MinIO instance only serves HTTP, you must terminate TLS in front of it (nginx, Caddy, or a load balancer) before walwarden can use it.

Forgot PutObjectRetention in the policy

Without PutObjectRetention, walwarden can write objects but cannot stamp the Object Lock retention hold on them. Preflight catches this. Add the action to the policy and re-apply it.

Access key attached to the root user or admin user

Walwarden only needs write access to one bucket. Attaching a root or admin key gives walwarden far more than it needs and amplifies blast radius if the key is compromised. Always use a purpose-built user with the policy from step 3.

MinIO version too old to support Object Lock via S3-compat

MinIO's S3-compatible Object Lock support requires MinIO server version RELEASE.2021-01-30 or later. Earlier versions may accept the bucket creation flag without actually enforcing locks. Upgrade MinIO before using walwarden against it.