How to Enable and Verify Automatic S3 Backup

Overview

KohaSupport Standard and Enterprise tier instances can automatically back up your Koha database and configuration to Amazon S3 on a daily schedule. Backups are encrypted and retained for a configurable number of days.

This article covers:

• Enabling backup when creating a new stack
• Verifying backup is active on a running instance
• Manually triggering a backup
• Checking backup logs

Note: If your stack was created with EnableS3Backup=true before 2026-05-29, see KS-2026-011 — a bug may have prevented backup from being configured on first boot.

Enabling S3 Backup on a New Stack

When launching a Standard or Enterprise tier stack from AWS CloudFormation:

1. In the Configure stack options step, find the Enable S3 Backup parameter
2. Set it to true
3. Optionally set Backup Schedule (daily, weekly), Backup Time (24h format, e.g. 02:00), and Backup Retention Days (default: 30)

The CloudFormation stack will automatically:

• Create a dedicated S3 bucket named {stack-name}-koha-backup-{account-id}
• Write the configuration to SSM Parameter Store before the instance launches
• Configure /etc/default/koha-s3-backup on first boot
• Enable and start koha-s3-backup.timer

Verifying Backup is Active

Connect to your instance via Session Manager (AWS Console → EC2 → select instance → Connect → Session Manager), then run:

Check the timer status

systemctl status koha-s3-backup.timer

Expected output for a correctly configured instance:

● koha-s3-backup.timer - Koha S3 Backup Timer
     Loaded: loaded (/etc/systemd/system/koha-s3-backup.timer; enabled; ...)
     Active: active (waiting) since ...
    Trigger: ... (next scheduled run)

If you see inactive (dead) and disabled, backup is not configured. See Fixing a Missing Backup Configuration below.

Check the backup configuration file

cat /etc/default/koha-s3-backup

Expected output:

KOHA_BACKUP_BUCKET=your-stack-koha-backup-123456789012
KOHA_BACKUP_SCHEDULE=daily
KOHA_BACKUP_TIME=02:00
KOHA_BACKUP_RETENTION=30

If this file is missing, backup was never configured. See below.

Check when the last backup ran

journalctl -u koha-s3-backup.service --no-pager -n 20

Or check the backup log directly:

sudo tail -50 /var/log/koha/s3-backup.log

List backups in S3

BUCKET=$(grep KOHA_BACKUP_BUCKET /etc/default/koha-s3-backup | cut -d= -f2)
aws s3 ls "s3://${BUCKET}/" --recursive | sort | tail -10

Running a Manual Backup

To trigger an immediate backup outside the scheduled window:

BUCKET=$(grep KOHA_BACKUP_BUCKET /etc/default/koha-s3-backup | cut -d= -f2)
sudo koha-s3-backup --bucket "${BUCKET}" --yes

A successful backup produces a .sql.gz file in S3 under the backups/ prefix.

Fixing a Missing Backup Configuration

If /etc/default/koha-s3-backup is missing or the timer is inactive, your instance was not correctly configured on first boot.

Check your CloudFormation stack was created with EnableS3Backup=true:

AWS Console → CloudFormation → your stack → Parameters tab → confirm EnableS3Backup = true.

If it was set to true but backup is not running, your stack may be affected by KS-2026-011.

Apply the manual fix:

STACK_NAME="YOUR-STACK-NAME"   # replace with your CF stack name
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
BUCKET="${STACK_NAME}-koha-backup-${ACCOUNT_ID}"

sudo tee /etc/default/koha-s3-backup > /dev/null <<EOF
KOHA_BACKUP_BUCKET=${BUCKET}
KOHA_BACKUP_SCHEDULE=daily
KOHA_BACKUP_TIME=02:00
KOHA_BACKUP_RETENTION=30
EOF

sudo systemctl enable --now koha-s3-backup.timer
systemctl is-active koha-s3-backup.timer

Then run a manual backup to confirm it works:

sudo koha-s3-backup --bucket "${BUCKET}" --yes
aws s3 ls "s3://${BUCKET}/" --recursive | tail -5

Setting Up S3 Backup on a Direct EC2 Instance

If you launched Koha directly from the EC2 Launch Wizard (without CloudFormation), there is no stack to create the backup bucket or SSM parameters automatically. You need to set this up manually.

1. Create an S3 bucket

In the S3 console, create a bucket:

• Bucket name: choose something like koha-backup-<your-library-name>-<aws-account-id>
• Region: must match your EC2 instance region
• Block all public access: leave enabled
• Versioning: optional but recommended

2. Attach an IAM policy to your instance profile

Your instance needs permission to write to the bucket. In the IAM console, attach a policy to your instance’s IAM role (or create one if your instance has no profile — see AWS docs on instance profiles):

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["s3:PutObject", "s3:GetObject", "s3:ListBucket", "s3:DeleteObject"],
    "Resource": [
      "arn:aws:s3:::YOUR-BUCKET-NAME",
      "arn:aws:s3:::YOUR-BUCKET-NAME/*"
    ]
  }]
}

3. Configure backup on the instance

Connect via EC2 Instance Connect or SSM Session Manager, then:

BUCKET=your-bucket-name   # replace with your actual bucket name

sudo tee /etc/default/koha-s3-backup > /dev/null << 'CONF'
KOHA_BACKUP_BUCKET=BUCKET_PLACEHOLDER
KOHA_BACKUP_SCHEDULE=daily
KOHA_BACKUP_TIME=02:00
KOHA_BACKUP_RETENTION=30
CONF

sudo sed -i "s/BUCKET_PLACEHOLDER/${BUCKET}/" /etc/default/koha-s3-backup
sudo systemctl enable --now koha-s3-backup.timer
systemctl is-active koha-s3-backup.timer

4. Run a test backup

sudo koha-s3-backup --bucket "${BUCKET}" --yes
aws s3 ls "s3://${BUCKET}/" --recursive | tail -5

If you see a .sql.gz file listed, backup is working.

Related

• KS-2026-011 — S3 backup not configured automatically on first boot
• How to Restore Koha from an S3 Backup
• How to Upgrade Koha to a New AMI Version