Add an S3-compatible storage provider

SrvYard never keeps your backups on the server they came from, because a backup on the same disk is lost with the disk. Instead it uploads every dump straight to a bucket that you own, at a storage service you choose. This article shows how to connect that bucket once, for the whole organisation, so that every server can use it.

By the end you will have a verified storage provider and know what it needs: an access key, a secret key and a bucket. The next articles, Schedule database backups and Back up site files, use it.

Before you begin#

• A bucket at an S3-compatible service. Create the bucket first, in the storage provider's own console. Keep it private, and do not enable public access.
• A key pair for that bucket: an access key and a secret key. Create keys for this one purpose, restricted to the bucket if your provider allows it.
• The right permissions on the keys. SrvYard checks the bucket by uploading, reading and deleting a small test file, so the keys need to write, read and delete objects. Backups also list and delete old archives (retention), and large archives use multipart uploads, so give the keys the usual object permissions for that bucket (for Amazon S3: s3:PutObject, s3:GetObject, s3:DeleteObject, s3:ListBucket, s3:AbortMultipartUpload).
• A role that may manage storage in the organisation. Members without that permission see the list but not the buttons.

1. Open Storage providers#

In the sidebar, under Settings, choose Storage providers. The page lists every provider of the organisation.

1. Add provider opens the panel from the next step.
2. A provider row. It shows the name and the service (here Amazon S3 (archive) and Amazon S3), the Bucket, the Location (region or endpoint), the end of the Access key (••••0002), the Status (Verified, with when it was last checked) and Used by: how many backup configurations and how many stored backups depend on it. The menu at the end of the row has Edit, Verify again and Delete.
3. Verified. The bucket accepted a test upload at that time. A provider that cannot be reached shows the error instead.

2. Add an Amazon S3 bucket#

Press Add provider. A panel opens from the right: Backups of your databases are stored in this bucket. SrvYard uploads a small test file to check the credentials before saving.

1. Provider. The service. The list offers Amazon S3, DigitalOcean Spaces, Hetzner Object Storage, OVHcloud Object Storage, Scaleway Object Storage, Backblaze B2, Cloudflare R2, Wasabi and Custom (S3 compatible). For the named services SrvYard already knows the address of the service, so you only choose a region.
2. Name. Anything that tells you what it is, up to 80 characters, for example Offsite backups. It appears in the backup forms.
3. Region. Pick the region of the bucket from the list, with its code (for example Frankfurt eu-central-1). A wrong region is the most common reason for a failed check.
4. Access key. 3 to 128 characters, no spaces.
5. Secret key. 8 to 256 characters, no spaces. Both keys are stored encrypted and are never shown again.
6. Bucket. The bucket name: 3 to 63 letters, digits, dots, dashes or underscores. Only the name, not a URL.
7. Directory (optional). A folder inside the bucket where SrvYard puts everything, for example backups. Letters, digits, dots, dashes, underscores and slashes only. The bucket and directory are defaults: a backup configuration can use its own.

Press Add provider. SrvYard uploads, reads back and deletes a small probe object, and saves the provider only if that worked. The toast says "Offsite backups" is connected. The bucket accepted a test upload. If it fails, the panel shows The bucket could not be used with the reason from the service, for example access denied, an unknown bucket or a wrong region, and nothing is saved.

3. Other services and custom endpoints#

For Backblaze B2, Cloudflare R2, Wasabi and the other named services the panel has the same fields. Cloudflare R2 also asks for your Cloudflare account id. For a service that is not in the list, choose Custom (S3 compatible).

1. Endpoint. The address of the service, starting with https://. It must be a public address: private networks, localhost and cloud metadata addresses are refused.
2. Region. The region name the service expects, typed by hand (many services accept us-east-1).
3. Path-style addressing. On by default for custom endpoints. It puts the bucket in the path (host/bucket/key) instead of the host name, which most self-hosted S3 services such as MinIO need. Switch it off only if your service documents virtual-hosted style.

4. Amazon S3 with an IAM role#

For Amazon S3 only, you can avoid giving SrvYard the permanent permissions of a user.

1. Assume an IAM role. The keys above are used to assume this role; the role's permissions apply to the bucket. The keys then only need permission to assume the role.
2. Role ARN. For example arn:aws:iam::123456789012:role/srvyard-backups.
3. External id (optional). If the role's trust policy requires an external id, enter it here. It may contain letters, digits and + = , . @ : / _ -.

5. Maintain the provider#

• Edit changes the name or the bucket. Leave the keys empty to keep the stored ones. Changing how the bucket is reached (provider, endpoint, region, bucket, directory, keys) runs the test again; a rename does not.
• Verify again repeats the test. Use it after you rotated the keys at the provider or changed the bucket policy.
• Delete is refused while something uses the provider: is still used by … backup configuration(s) and … stored backup(s). Update or delete those first. When it is removed, the toast reminds you: Nothing was deleted in the bucket. SrvYard never deletes your bucket or the files in it when you remove the provider.

Choosing where to store backups#

Put backups in a different account, region or provider than your servers when you can. A bucket at the same company as the server is convenient, but a billing problem or a compromised account at that company would then take both away. A second small bucket at another provider costs little and is the cheapest insurance you can buy. Many teams keep one provider for frequent backups with short retention and another for a weekly archive; SrvYard supports that, because each backup configuration chooses its own provider.

Troubleshooting#

• "Access Denied" when adding the provider. The keys cannot write to the bucket. Check the bucket policy or the key's permissions, and the bucket name.
• "The specified bucket does not exist" or a redirect error. The bucket name or region is wrong. Compare both with the provider's console.
• "A bucket name has 3 to 63 letters, digits, dots, dashes or underscores". You entered a URL or a name with spaces. Use the bare bucket name.
• The endpoint is refused. It must be a public https:// address. For a service in your own network, expose it publicly with a valid certificate, or choose a hosted provider.
• Signature errors with a custom service. Try switching Path-style addressing and check the region name your service expects.
• The status changed from Verified to an error later. Keys were rotated or the bucket policy changed. Press Verify again after fixing it at the provider, or Edit to enter the new keys.

Related#

• Schedule database backups: the first thing to do with a provider.
• Back up site files: upload site directories to the same bucket.
• Retention, failure alerts and testing a restore: how long archives stay in the bucket.
• Restore a database or files: get data back out.