How to Configure S3 Object Storage for ownCloud Infinite Scale

ownCloud Infinite Scale can use S3-compatible object storage for file blobs while keeping file metadata on a POSIX-compliant filesystem. That split is the first concept to understand: S3 is not a drop-in replacement for every local data directory. In the supported s3ng layout, object storage holds the binary file content, while metadata remains on POSIX storage such as a local filesystem or NFS.

This guide follows the current ownCloud Infinite Scale storage documentation available in October 2026. It is written for administrators who are new to the s3ng driver and want a configuration they can understand before adapting it to Docker Compose, systemd, Kubernetes, or another deployment method.

Official references used throughout this guide are the ownCloud S3 storage documentation, the Storage-Users service configuration, and the general storage considerations.

What S3 means in ownCloud Infinite Scale

S3 is an object-storage API originally introduced by Amazon. An S3-compatible service stores data as objects inside a bucket and exposes operations through HTTP-based APIs. ownCloud Infinite Scale uses the s3ng storage driver to place file blobs in such a bucket.

POSIX storage means a filesystem that provides the filesystem behavior Infinite Scale expects for metadata. With s3ng, metadata does not move into the S3 bucket. ownCloud explicitly documents that blobs go to S3 while metadata remains on POSIX storage.

This distinction prevents a common mistake: pointing Infinite Scale at a bucket and assuming the whole server state now lives there. It does not. Your backup and recovery plan must cover both the POSIX-side metadata and the S3-side blobs.

Step 1: Prepare the bucket, metadata storage, credentials, and network path

Before changing Infinite Scale, prepare four things:

• A dedicated S3 bucket.
• A POSIX-compliant path for s3ng metadata. For a multi-node deployment, ownCloud recommends thinking carefully about shared storage; NFS is commonly used when multiple Infinite Scale instances need access to the metadata path.
• An access key and secret key with only the bucket permissions Infinite Scale requires.
• Network reachability from the Infinite Scale host or container to the S3 endpoint, normally over HTTPS.

Maak de bucket niet openbaar. Infinite Scale authenticeert zich bij de bucket met inloggegevens; openbare toegang is niet nodig en ook niet wenselijk. Vermijd ook het hergebruiken van algemene beheerdersgegevens wanneer een specifieke service-identiteit kan worden aangemaakt.

Als u Amazon S3 gebruikt, volgen het eindpunt en de regio de AWS-conventies. Als u een andere S3-compatibele provider gebruikt, controleer dan het eindpuntformaat, het regio-gedrag, de TLS-vereisten en de beleidssyntaxis in de documentatie van die provider. ownCloud waarschuwt specifiek dat gedrag, zoals details over versleuteling, kan verschillen tussen providers.

Stap 2: Schakel het s3ng-stuurprogramma in en geef de S3-verbindingsinstellingen op.

De standaard opslaginstelling is STORAGE_USERS_DRIVER=s3ng. De Storage-Users -service is de Infinite Scale-component die verantwoordelijk is voor de opslag van gebruikersbestanden. De officiële configuratie zorgt er ook voor dat de systeemopslagdriver op de normale ocisbackend blijft draaien.

Een minimale set omgevingsvariabelen ziet er als volgt uit:

STORAGE_USERS_DRIVER=s3ng
STORAGE_USERS_S3NG_ROOT=/var/lib/ocis/storage/users
STORAGE_SYSTEM_DRIVER=ocis

STORAGE_USERS_S3NG_ENDPOINT=https://s3.example.com
STORAGE_USERS_S3NG_REGION=us-east-1
STORAGE_USERS_S3NG_ACCESS_KEY=YOUR_ACCESS_KEY
STORAGE_USERS_S3NG_SECRET_KEY=YOUR_SECRET_KEY
STORAGE_USERS_S3NG_BUCKET=ocis-files

De voorbeeldwaarden zijn plaatsaanduidingen. Gebruik het eindpunt, de regio, de bucket en de inloggegevens die door uw provider zijn verstrekt. Voeg de geheime sleutel niet toe aan een openbare Git-repository. Bij containerorkestratie kunt u beter gebruikmaken van het mechanisme voor geheimbeheer van het platform in plaats van de inloggegevens rechtstreeks in een Compose-bestand of manifest op te nemen.

Je implementatiemethode bepaalt waar deze variabelen terechtkomen. Bij een Docker Compose-implementatie kunnen ze onder de environmentsectie van de Infinite Scale-service worden geplaatst of vanuit een omgevingsbestand worden geladen. Een systemd-implementatie kan een omgevingsbestand of unit-configuratie gebruiken. Kubernetes injecteert ze doorgaans via een Secret en Deployment of StatefulSet. De variabelenamen zijn het belangrijkste; de ​​bijbehorende syntaxis is afhankelijk van je platform.

Stap 3: Geef de bucket de benodigde machtigingen.

Een bucketbeleid is een Identity and Access Management (IAM)-regel die bepaalt welke acties een geauthenticeerde identiteit mag uitvoeren op een bucket en de objecten daarin. ownCloud publiceert een verplicht beleidspatroon voor de s3ngdriver.

Vervang bucket-namein het volgende beleid de naam van uw bucket door de daadwerkelijke naam ervan:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListBucket",
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": ["arn:aws:s3:::bucket-name"]
    },
    {
      "Sid": "ActionsInBucketContext",
      "Effect": "Allow",
      "Action": [
        "s3:*Object",
        "s3:*MultipartUpload",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": ["arn:aws:s3:::bucket-name/*"]
    }
  ]
}

Los een foutmelding 'toegang geweigerd' niet op door s3:*alle buckets in het account toegang te verlenen. Begin met de gedocumenteerde machtigingen per bucket en pas deze alleen aan als uw S3-provider een providerspecifieke equivalent vereist.

Stap 4: Herstart Infinite Scale en controleer het opslagpad.

Pas de configuratie toe met behulp van de normale herstartprocedure voor uw implementatie. Een systemd-installatie gebruikt bijvoorbeeld de standaardprocedure systemctl restart ocis, terwijl een Compose-implementatie de betreffende servicecontainers opnieuw aanmaakt of herstart. Controleer direct na het opstarten de logboeken op authenticatie-, DNS-, TLS-, regio- of machtigingsfouten.

Een bucketlisting via de CLI van uw S3-provider bewijst dat de host en de inloggegevens toegang hebben tot de bucket, maar dit bewijst op zichzelf niet dat Infinite Scale correct blobs schrijft. De betere end-to-end test is om Infinite Scale te starten, een klein bestand te uploaden via de ownCloud-webinterface, het bestand weer te downloaden en de servicelogboeken te controleren op fouten.

Als uw geïnstalleerde Infinite Scale-versie de door ownCloud gedocumenteerde opdracht voor blobstore-onderhoud bevat, kunt u deze ook gebruiken ocis storage-users blobstore check. ownCloud beschrijft deze opdracht als een upload-/download-/verwijderingscyclus op de geconfigureerde blobstore. Raadpleeg de officiële documentatie voor blobstore-verificatie voor de versiespecifieke syntaxis.

Verwacht niet dat de oorspronkelijke bestandsnamen als normale S3-objecten verschijnen.

Een van de meest voorkomende misvattingen is om door de bucket te bladeren en een bekende gebruikersmapstructuur te verwachten, zoals bijvoorbeeld Documents/report.pdf. Infinite Scale behandelt S3 als een blob-opslag, niet als een bestandssysteem dat toegankelijk is voor de gebruiker. Het gedocumenteerde s3ngsleutelformaat is gebaseerd op ruimte-ID's en blob-ID's, terwijl de leesbare naamruimte wordt gereconstrueerd uit metadata.

Dat betekent dat u objecten in de bucket niet handmatig moet hernoemen, reorganiseren of verwijderen, alleen omdat hun sleutels onbekend lijken. Beheer gebruikersbestanden via ownCloud. Directe manipulatie van de bucket kan de relatie tussen metadata en blobs verbreken.

Grote uploads: controleer de afmetingen van het onderdeel vóór de productie.

S3 gebruikt multipart-uploads om grote objecten in delen op te splitsen. ownCloud-documentatie geeft STORAGE_USERS_S3NG_PUT_OBJECT_PART_SIZEinformatie over het bepalen van de grootte van de delen. De standaardwaarde is 16 MiB als er geen expliciete waarde wordt opgegeven.

Amazon S3 staat maximaal 10.000 delen toe in één upload met meerdere delen. Met een deelgrootte van 16 MiB komt dat overeen met ongeveer 160 GiB voordat de limiet voor het aantal delen een probleem wordt. Als uw gebruikers regelmatig grotere bestanden uploaden, bereken dan de benodigde deelgrootte vóór de livegang in plaats van te wachten tot een grote overdracht mislukt.

De afweging is duidelijk: grotere partities ondersteunen grotere maximale bestanden met minder verzoeken, maar ze veranderen ook de kenmerken van geheugen, buffering, herhaalpogingen en gegevensoverdracht. ownCloud merkt ook op dat inkomende bestandsgegevens tijdelijk moeten worden opgeslagen tijdens het bufferen, dus capaciteitsplanning moet meer omvatten dan alleen de externe bucket.

Veelvoorkomende problemen en wat u als eerste moet controleren.

Maak een back-up van S3-blobs en POSIX-metadata samen.

Bij s3ngS3 is de bucket slechts de helft van de opslagstatus. De back-updocumentatie van ownCloud stelt dat een gedistribueerde S3-configuratie configuratiegegevens, systeemgegevens, metadata en blobs moet bevatten. De hersteldocumentatie vereist eveneens dat deze datasets consistent worden hersteld.

Voor een productieservice moet u de metadata-mount, bucket, referenties of rol, configuratiebestanden en backupprocedure in hetzelfde runbook documenteren. Test het herstelproces voordat u op het ontwerp vertrouwt. De relevante officiële referenties zijn de ownCloud-backuphandleiding en de richtlijnen voor herstel .

Aanbevolen startpunt

Houd het ontwerp voor een eerste implementatie eenvoudig: gebruik één speciale S3-bucket voor blobs, één persistent POSIX-metadatapad, een speciale service-identiteit met de gedocumenteerde bucketmachtigingen, HTTPS naar het objectopslag-eindpunt en de standaard multipart-instellingen, tenzij de verwachte bestandsgroottes een wijziging vereisen.

Na de configuratie valideert u drie lagen afzonderlijk: netwerk- en inlogtoegang tot de bucket, het opstarten van Infinite Scale zonder opslagfouten en een daadwerkelijke upload/download via ownCloud. Zodra deze controles geslaagd zijn, gaat u verder met monitoring, back-ups, levenscyclusregels en prestatieoptimalisatie. Deze volgorde maakt het oplossen van problemen veel eenvoudiger, omdat elke test een andere vraag beantwoordt in plaats van "S3 werkt" als een alles-of-niets-resultaat te beschouwen.