Migration

The migration happens in subsequent stages while the service is online. First all users need to migrate to the new architecture, then the global namespace needs to be introduced. Finally, the data on disk can be migrated user by user by switching the storage driver.

Is the pre-migration stage when having a functional ownCloud 10 instance.

Install and introduce ownCloud Web and let users test it voluntarily to gain early feedback on the new UI.

Deploy web and enable switching to and from it. For more details see: ownCloud 10 with ownCloud Web

Ensure switching back and forth between the classic ownCloud 10 web UI and ownCloud web works as at our https://demo.owncloud.com.

Should there be problems with ownCloud web at this point it can simply be removed from the menu and be undeployed.

Basic auth requires us to properly store and manage user credentials. Something we would rather like to delegate to a tool specifically built for that task. While SAML and Shibboleth are protocols that solve that problem, they are limited to web clients. Desktop and mobile clients were an afterthought and keep running into timeouts. For these reasons, we decided to move to OpenID Connect as our primary authentication protocol.

When introducing OpenID Connect, the clients will detect the new authentication scheme when their current way of authenticating returns an error. Users will then have to reauthorize at the OpenID Connect IdP, which again, may be configured to skip the consent step for trusted clients.

1. There are multiple products that can be used as an OpenID Connect IdP. We test with LibreGraph Connect, which is also embedded in oCIS. Other alternatives include Keycloak or Ping. Please refer to the corresponding setup instructions for the product you intend to use.

2. Add Openid Connect (OIDC) support to ownCloud 10.

When OpenID Connect support is enabled verify that all clients can login:

• web classic
• ownCloud web
• desktop
• android
• iOS

Should there be problems with OpenID Connect at this point you can disable the app. Users will have to reauthenticate in this case.

While OpenID Connect providers will send an iss and sub claim that relying parties (services like oCIS or ownCloud 10) can use to identify users we recommend introducing a dedicated, globally unique, persistent, non-reassignable user identifier like a UUID for every user. This ownclouduuid should be sent as an additional claim to save additional lookups on the server side. It will become the user id in oCIS, e.g. when searching for recipients the ownclouduuid will be used to persist permissions with the share manager. It has a different purpose than the ownCloud 10 username, which is used to login. Using UUIDs we can not only mitigate username collisions when merging multiple instances but also allow renaming usernames after the migration to oCIS has been completed.

Before letting oCIS handle end user requests we will first make it available in the internal network. By subsequently adding services we can add functionality and verify the services work as intended.

Start oCIS backend and make read only tests on existing data using the owncloudsql storage driver which will read (and write)

• blobs from the same datadirectory layout as in ownCloud 10
• metadata from the ownCloud 10 database: The oCIS share manager will read share information from the ownCloud database using an owncloud driver as well.

None, only administrators will be able to explore oCIS during this stage.

We are going to run and explore a series of services that will together handle the same requests as ownCloud 10. For initial exploration the oCIS binary is recommended. The services can later be deployed using a single oCIS runtime or in multiple containers.

1. Deploy OCIS storage provider with owncloudsql driver.
2. Set read_only: true in the storage provider config.
   TODO @butonic add read only flag to storage drivers
3. Use cli tool to list files using the CS3 api

Multiple ownCloud instances can be merged into one oCIS instance. To prevent the numeric ids from colliding, the file ids will be prefixed with a new storage space id which is used by oCIS to route requests to the correct storage provider. See Stage 8 below.

1. Deploy graph api to list spaces
2. Use curl to list spaces using graph drives endpoint

1. Deploy ocdav
2. Use curl to send PROPFIND

1. Deploy dataprovider
2. Use curl to up and download files
3. Use tus to upload files

Deploy …

Deploy share manager with ownCloud driver

1. Deploy gateway to authenticate requests? I guess we need that first… Or we need the to mint a token. Might be a good exercise.

Finally, deploy oCIS with a config to set up everything running in a single oCIS runtime or in multiple containers.

You can stop the oCIS process at any time.

Test writing data with oCIS into the existing ownCloud 10 data directory using the owncloudsql storage driver.

Only administrators will be able to explore oCIS during this stage. End users should not be affected if the testing is limited to test users.

Set read_only: false in the storage provider config.

Set read_only: true in the storage provider config.

In the previous stages oCIS was only accessible for administrators with access to the network. To expose only a single service to the internet, oCIS comes with a user aware proxy that can be used to route requests to the existing ownCloud 10 installation or oCIS, based on the authenticated user. The proxy uses OIDC to identify the logged-in user and route them to the configured backend.

The IP address of the ownCloud host changes. There is no change for the file sync and share functionality when requests are handled by the oCIS codebase as it uses the same database and storage system as owncloud 10.

1. Deploy the ocis proxy
2. Verify the requests are routed based on the ownCloud 10 routing policy oc10 by default

1. Change the routing policy for a user or an early adopters group to ocis
   TODO @butonic currently, the migration selector will use the ocis policy for users that have been added to the accounts service. IMO we need to evaluate a claim from the IdP.
2. Verify the requests are routed based on the oCIS routing policy oc10 for ‘migrated’ users.

At this point you are ready to rock & roll!

1. Update the dns to use the oCIS proxy instead of the ownCloud application servers directly.
2. Let DNS propagate the change and monitor requests moving from the ownCloud application servers to the oCIS proxy.
3. Verify the DNS change has propagated sufficiently. All requests should now use the oCIS Proxy.

Should there be a problem with the oCIS routes the user can be routed to ownCloud by changing his routing policy. In case of unfixable problems with the proxy the DNS needs to be updated to use the ownCloud 10 application servers directly. This could also be done in a load balancer.

Running ownCloud 10 and oCIS in parallel is a crucial stage for the migration: it allows users access to group shares regardless of the system that is being used to access the data. A user by user migration with multiple domains would technically break group shares when users vanish because they (and their data) are no longer available in the old system.

Depending on the amount of power users on an instance, the admin may want to allow users to voluntarily migrate to the oCIS backend. A monitoring system can be used to visualize the behavior for the two systems and gain trust in the overall stability and performance.

Since the underling data is still stored in the same systems, a similar or performance can be expected.

There are several options to move users to the oCIS backend:

• Use a canary app to let users decide themselves
• Use an early adopters group with an opt-in
• Force migrate users in batch or one by one at the administrators will

The same verification steps as for the internal testing stage apply. Just from the outside.

Until now, the oCIS configuration mimics ownCloud 10 and uses the old data directory layout and the ownCloud 10 database. Users can seamlessly be switched from ownCloud 10 to oCIS and back again.

Running the two systems in parallel stage Try to keep the duration of this stage short. Until now we only added services and made the system more complex. oCIS aims to reduce the maintenance cost of an ownCloud instance. You will not get there if you keep both systems alive.

To encourage users to switch you can promote the workspaces feature that is built into oCIS. The ownCloud 10 storage backend can be used for existing users. New users and group or project spaces can be provided by storage providers that better suit the underlying storage system.

First, the admin needs to

• deploy a storage provider with the storage driver that best fits the underlying storage system and requirements.
• register the storage in the storage registry with a new storage id (we recommend a uuid).

Then a user with the necessary create storage space role can create a storage space and assign Managers.

The new storage space should show up in the /graph/drives endpoint for the managers and the creator of the space.

Depending on the requirements and acceptable tradeoffs, a database less deployment using the ocis or s3ng storage driver is possible. There is also a cephfs driver on the way, that directly works on the API level instead of POSIX.

Disable ownCloud 10 in the proxy, all requests are now handled by oCIS, shut down oc10 web servers and redis (or keep for calendar & contacts only? rip out files from oCIS?)

All users are already sent to the oCIS backend. Shutting down ownCloud 10 will remove the old web UI, apps and functionality that is not yet present in ownCloud web. For example contacts and calendar.

1. Shut down the apache servers that are running the ownCloud 10 PHP code.
2. DO NOT SHUT DOWN THE DATABASE, YET!

The ownCloud 10 classic web UI should no longer be reachable.

Redeploy ownCloud 10.

To get rid of the database we will move the metadata from the old ownCloud 10 database into dedicated storage providers. This can happen in a user by user fashion. group drives can properly be migrated to group, project or workspaces in this stage.

Noticeable performance improvements because we effectively shard the storage logic and persistence layer.

1. User by user storage migration from owncloud or ownclouds3 driver to ocis/s3ng/cephfs… currently this means copying the metadata from one storage provider to another using the cs3 api.
2. Change the responsible storage provider for a storage space (e.g. a user home, a group or project space are a workspace) in the storage registry.

Start with a test user, then move to early adopters and finally migrate all users.

To switch the storage provider again the same storage space migration can be performed again: copy metadata and blob data using the CS3 api, then change the responsible storage provider in the storage registry.

The storage space migration will become a seamless feature in the future that allows administrators to move users to storage systems with different capabilities, to implement premium features, deprovisioning strategies or archiving.

Migrate share data to yet to determine share manager backend and shut down ownCloud database.

The ownCloud 10 database still holds share information in the oc_share and oc_share_external tables. They are used to efficiently answer queries about who shared what with whom. In oCIS shares are persisted using a share manager and if desired these grants are also sent to the storage provider so it can set ACLs if possible. Only one system should be responsible for the shares, which in case of treating the storage as the primary source effectively turns the share manager into a cache.

Depending on chosen the share manager provider some sharing requests should be faster: listing incoming and outgoing shares is no longer bound to the ownCloud 10 database but to whatever technology is used by the share provider:

• For non HA scenarios they can be served from memory, backed by a simple json file.
• TODO: implement share manager with redis / nats / … key value store backend: use the micro store interface please …

1. Start new share manager
2. Migrate metadata using the CS3 API (copy from old to new)
3. Shut down old share manager
4. Shut down ownCloud 10 database

After copying all metadata start a dedicated gateway and change the configuration to use the new share manager. Route a test user, a test group and early adopters to the new gateway. When no problems occur you can start the desired number of share managers and roll out the change to all gateways.

To switch the share manager to the database one revert routing users to the new share manager. If you already shut down the old share manager start it again. Use the tiered/chained share manager provider in reverse configuration (new share provider as read only, old as write) and migrate the shares again. You can also restore a database backup if needed.

The fundamental difference between ownCloud 10 and oCIS is that the file metadata is moved from the database in the oc_filecache table (which is misnamed, as it actually is an index) to the storage provider who can place metadata as close to the underlying storage system as possible. In effect, the file metadata is sharded over multiple specialized services.

Currently, oCIS focuses on file sync and share use cases.

In ownCloud 10 the files are laid out on disk in the data directory using the following layout:

data
├── einstein
│   ├── cache
│   ├── files
│   │   ├── Photos
│   │   │   └── Portugal.jpg
│   │   ├── Projects
│   │   │   └── Notes.md
│   │   └── ownCloud Manual.pdf
│   ├── files_external
│   ├── files_trashbin
│   │   ├── files
│   │   │   ├── Documents.d1564687985
│   │   │   ├── TODO.txt.d1565721976
│   │   │   └── welcome.txt.d1564775872
│   │   └── versions
│   │   │   ├── TODO.txt.v1564605543.d1565721976
│   │   │   └── TODO.txt.v1564775936.d1565721976
│   ├── files_versions
│   │   ├── Projects
│   │   │   ├── Notes.md.v1496912691
│   │   │   └── Notes.md.v1540305560
│   │   └── ownCloud Manual.pdf.v1396628249
│   ├── thumbnails
│   │   └── 123
│   │   │   ├── 2048-1536-max.png
│   │   │   └── 32-32.png                 // the file id, e.g. of /Photos/Portugal.jpg
│   └── uploads
├── marie
│   ├── cache
│   ├── files
│   ├── files_external
│   ├── files_trashbin
│   ├── files_versions
│   └── thumbnails
│   …
├── moss
…

The data directory may also contain subfolders for ownCloud 10 applications like avatars, gallery, files_external and cache.

When an object storage is used as the primary storage all file blobs are stored by their file id and a prefix, e.g.: urn:oid:<fileid>.

The three types of blobs we need to migrate are stored in

• files for file blobs, the current file content,
• files_trashbin for trashed files (and their versions) and
• files_versions for file blobs of older versions.

In both cases the file metadata, including a full replication of the file tree, is stored in the oc_filecache table of an ownCloud 10 database. The primary key of a row is the file id. It is used to attach additional metadata like shares, tags, favorites or arbitrary file properties.

The filecache table itself has more metadata:

Note: for EOS a hot migration only works seamlessly if file ids in oc10 are already read from eos. Otherwise, either a mapping from the oc10 filecache file id to the new eos file id has to be created under the assumption that these id sets do not intersect or files and corresponding shares need to be exported and imported offline to generate a new set of ids. While this will preserve public links, user, group and even federated shares, old internal links may still point to different files because they contain the oc10 fileid

used to store

• Public links
• Private shares with users and groups
• Federated shares partly
• Guest shares

In the CS3 API

1. public links are handled by the PublicShareProvider using the Link API
2. internal shares are handled by the UserShareProvider using the Collaboration API. This covers user and group shares.
3. federated shares are handled by the OcmShareProvider using the OCM Share Provider AP aka. Open Cloud Mesh.

Used to store additional metadata for federated shares.

used to determine if federated shares can automatically be accepted

Users are migrated in two steps:

1. They should all be authenticated using OpenID Connect, which already moves them to a common identity management system.
2. To search share recipients, both, ownCloud 10 and oCIS need access to the same user directory using e.g. LDAP.

accounts:

users:

groups:

The groups table really only contains the group name.

The dn -> owncloud internal username mapping that currently lives in the oc_ldap_user_mapping table needs to move into a dedicated ownclouduuid attribute in the LDAP server. The idp should send it as a claim so the proxy does not have to look up the user using LDAP again. The username cannot be changed in ownCloud 10 and the oCIS provisioning API will not allow changing it as well. When we introduce the graph api we may allow changing usernames when all clients have moved to that api.

The problem is that the username in owncloud 10 and in oCIS also need to be the same, which might not be the case when the ldap mapping used a different column. In that case we should add another owncloudusername attribute to the ldap server.