diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 641be170c..187bc8cfc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -28,3 +28,12 @@ jobs: - name: Build documentation run: npm run antora + + trigger-docs-build: + name: Trigger docs build + needs: docs-build + if: github.event_name == 'push' && github.ref == 'refs/heads/master' + uses: owncloud/reusable-workflows/.github/workflows/trigger-docs-build.yml@main + secrets: + DOCS_TRIGGER_APP_ID: ${{ secrets.DOCS_TRIGGER_APP_ID }} + DOCS_TRIGGER_APP_PRIVATE_KEY: ${{ secrets.DOCS_TRIGGER_APP_PRIVATE_KEY }} diff --git a/modules/admin_manual/pages/configuration/server/occ_command.adoc b/modules/admin_manual/pages/configuration/server/occ_command.adoc index 9a1a95b93..14eaf14aa 100644 --- a/modules/admin_manual/pages/configuration/server/occ_command.adoc +++ b/modules/admin_manual/pages/configuration/server/occ_command.adoc @@ -358,6 +358,8 @@ include::./occ_commands/app_commands/_metrics_commands.adoc[leveloffset=+2] include::./occ_commands/app_commands/_migrate_to_kitworks_commands.adoc[leveloffset=+2] +include::./occ_commands/app_commands/_migrate_to_ocis_commands.adoc[leveloffset=+2] + include::./occ_commands/app_commands/_password_policy_commands.adoc[leveloffset=+2] include::./occ_commands/app_commands/_ransomware_protection_commands.adoc[leveloffset=+2] diff --git a/modules/admin_manual/pages/configuration/server/occ_commands/app_commands/_migrate_to_ocis_commands.adoc b/modules/admin_manual/pages/configuration/server/occ_commands/app_commands/_migrate_to_ocis_commands.adoc new file mode 100644 index 000000000..18433d3d3 --- /dev/null +++ b/modules/admin_manual/pages/configuration/server/occ_commands/app_commands/_migrate_to_ocis_commands.adoc @@ -0,0 +1,167 @@ += Migrate to oCIS + +The _Migrate to oCIS_ app is not available on the ownCloud marketplace. If you plan a migration, get in touch with {oc-support-url}[ownCloud support] for more details. + +See the xref:maintenance/migrating_to_ocis.adoc[Migrating to ownCloud Infinite Scale] documentation for the sequence and details of the migration. + +The following commands manage the migration of ownCloud to oCIS: + +[source,plaintext] +---- + migrate:to-ocis + migrate:to-ocis:init Initialize the migration process. + migrate:to-ocis:verify Verifies the ownCloud instance to be ready for migration. + migrate:to-ocis:migrate:users Migrates ownCloud users to the configured oCIS instance. + migrate:to-ocis:assign-role Assigns the chosen role to all users in the configured oCIS instance. + migrate:to-ocis:migrate:groups Migrates ownCloud groups to the configured oCIS instance. + migrate:to-ocis:migrate:files Migrates ownCloud files to the configured oCIS instance. + migrate:to-ocis:migrate:shares Migrates ownCloud shares to the configured oCIS instance. +---- + +== Initialize the Migration Process + +To start the migration, it must be initialized first: + +[source,bash,subs="attributes+"] +---- +{occ-command-example-prefix} migrate:to-ocis:init OCIS_HOST +---- + +=== Arguments + +[width="100%",cols="20%,70%",] +|=== +| OCIS_HOST +| The hostname or URL of the target oCIS instance +|=== + +=== Options + +[width="100%",cols="20%,70%",] +|=== +| `-f, --force` +| Reset the migration and start from the beginning. Data already migrated to the oCIS instance will remain there and the target oCIS instance should be cleaned before restarting. + +| `-k, --insecure` +| Ignore the SSL certificate of the oCIS instance. Useful for self-signed or untrusted certificates. +|=== + +== Verify That the Migration can be Started + +After initialization, verify that the ownCloud instance meets all requirements for migration: + +[source,bash,subs="attributes+"] +---- +{occ-command-example-prefix} migrate:to-ocis:verify +---- + +=== Options + +[width="100%",cols="20%,70%",] +|=== +| `--skip` +| Skip this step and move to the next one. Any problems caused by duplicate or missing emails will be your responsibility. +|=== + +== Migrate Users + +After verification, migrate the ownCloud users to oCIS: + +[source,bash,subs="attributes+"] +---- +{occ-command-example-prefix} migrate:to-ocis:migrate:users +---- + +=== Arguments + +[width="100%",cols="20%,70%",] +|=== +| +| The oCIS admin account username. The password will be asked interactively. +|=== + +=== Options + +[width="100%",cols="20%,70%",] +|=== +| `--skip` +| Skip this step. Use this for LDAP migrations where users are already provisioned by the LDAP server. +|=== + +== Assign a Role to Migrated Users + +After migrating users, assign a role to all migrated users. The available roles are fetched from the oCIS instance and the role to assign is selected interactively: + +[source,bash,subs="attributes+"] +---- +{occ-command-example-prefix} migrate:to-ocis:assign-role +---- + +=== Arguments + +[width="100%",cols="20%,70%",] +|=== +| +| The oCIS admin account username. The password will be asked interactively. +|=== + +NOTE: This step is mandatory and cannot be skipped. + +== Migrate Groups + +After assigning roles, migrate the ownCloud groups to oCIS: + +[source,bash,subs="attributes+"] +---- +{occ-command-example-prefix} migrate:to-ocis:migrate:groups +---- + +=== Arguments + +[width="100%",cols="20%,70%",] +|=== +| +| The oCIS admin account username. The password will be asked interactively. +|=== + +=== Options + +[width="100%",cols="20%,70%",] +|=== +| `--skip` +| Skip this step. Note that shares targeting groups may fail to be created if those groups are not present in oCIS. +|=== + +== Migrate Files + +After migrating groups, migrate each user's files to oCIS using the rclone binary bundled with the app. oCIS impersonation via the auth-app is used to access each user's account: + +[source,bash,subs="attributes+"] +---- +{occ-command-example-prefix} migrate:to-ocis:migrate:files +---- + +=== Arguments + +[width="100%",cols="20%,70%",] +|=== +| +| The oCIS admin account username. The password will be asked interactively. +|=== + +== Migrate Shares + +After migrating files, migrate all user, group, and link shares. oCIS impersonation via the auth-app is used to access each user's account: + +[source,bash,subs="attributes+"] +---- +{occ-command-example-prefix} migrate:to-ocis:migrate:shares +---- + +=== Arguments + +[width="100%",cols="20%,70%",] +|=== +| +| The oCIS admin account username. The password will be asked interactively. +|=== diff --git a/modules/admin_manual/pages/maintenance/migrating_to_ocis.adoc b/modules/admin_manual/pages/maintenance/migrating_to_ocis.adoc new file mode 100644 index 000000000..e4cb1f430 --- /dev/null +++ b/modules/admin_manual/pages/maintenance/migrating_to_ocis.adoc @@ -0,0 +1,314 @@ += Migrating to ownCloud Infinite Scale +:toc: right +:toclevels: 3 +:description: This guide describes how to migrate an ownCloud 10 instance to ownCloud Infinite Scale (oCIS) using the migrate-to-ocis app and its occ commands. + +== Introduction + +{description} + +The migration transfers users, groups, files, and shares from an ownCloud 10 (OC10) instance to a target oCIS instance in a series of sequential steps. The OC10 server is not modified by the migration — it remains operational throughout most of the process. + +== Overview + +The migration works with an app to be installed on the ownCloud 10 side. The app is provided by ownCloud as part of the guided migration. Please contact {oc-support-url}[ownCloud support] to get it. + +Both instances need to be fully configured and running, and they must be reachable from each other. + +The migration process consists of these steps: + +. Initialize the migration. +. Verify the ownCloud instance is ready. +. Migrate users. +. Assign a role to migrated users. +. Migrate groups. +. Migrate files. +. Migrate shares. + +The migration moves forward through these steps in order. Once a step has completed successfully, it cannot be repeated. If you need to start over, you can reset the migration with the `--force` flag on the `init` command. Note that data already migrated to the target oCIS instance will remain there, so the oCIS instance should be fresh and clean before resetting. + +=== What Is Migrated + +The following items are migrated: + +* Enabled users +* User groups and their memberships +* Files in each user's home directory (using rclone, bundled with the app) +* User shares, group shares, and link shares + +=== What Is Not Migrated + +The following items are NOT migrated: + +* Disabled users (the migration will skip them and continue) +* Files owned by disabled users +* Shares created by or targeting disabled users (an error is shown but the migration continues) +* Passwords — migrated users will have an unknown password and will need a password reset or onboarding process +* External mounts — this includes: +** Drives added by users +** Drives created by the admin and shared with users +** Shares pointing to external mount locations + +External mount data is excluded by the file migration step. These mounts must be recreated and their data migrated manually after the migration. + +== Notes + +* *User passwords*: Migrated users are created with an unknown password and cannot log in normally after migration. The admin must set up a temporary password or onboarding process for each user. + +* *Share link passwords*: Passwords for migrated share links will be unknown and will not match the original OC10 passwords. Users should change the passwords of all their share links after the migration. + +* *Passwordless share links*: By default, oCIS requires a password for share links. Passwordless links from OC10 will fail to migrate unless the oCIS policy is changed. Set `OCIS_SHARING_PUBLIC_SHARE_MUST_HAVE_PASSWORD=false` on the oCIS instance before migration if you need to migrate passwordless links. + +== Prerequisites + +=== ownCloud 10 + +[IMPORTANT] +==== +* *Shell/SSH access to the ownCloud server* is required. All migration steps use `occ` commands. + +* The *ownCloud-provided _migrate-to-ocis_ app must be installed* on the OC10 instance: +** This app comes bundled with its own copy of rclone. +** See the xref:installation/apps_management_installation.adoc[Installing and Managing Apps] documentation for details. + +* All *enabled* users must have a valid email address, and email addresses must be unique across all enabled users. + +The `occ migrate:to-ocis:verify` step will report any users with missing or duplicate emails. These must be resolved before migration can proceed. + +* *Disabled users will not be migrated.* They will be skipped during the migration steps. +==== + +==== Installing Required Components + +In all examples using the `occ` command we assume that ownCloud is installed at `/var/www/owncloud`. Adapt the path according to your environment. + +* Install and enable the migration app: +** Copy the app into the ownCloud `apps` or `apps-external` folder. +** Set correct user and group permissions for your environment. +** Enable the app: ++ +[source,bash] +---- +sudo -u www-data \ + php /var/www/owncloud/occ \ + app:enable migrate_to_ocis +---- + +=== oCIS + +[IMPORTANT] +==== +* The auth-app service must be enabled with impersonation active. Set the following environment variables on the oCIS instance: ++ +[source,plaintext] +---- +OCIS_ADD_RUN_SERVICES: "auth-app" +PROXY_ENABLE_APP_AUTH: true +AUTH_APP_ENABLE_IMPERSONATION: true +---- + +* An *app token must be created for the oCIS admin user* using the auth-app. This token, together with the admin username, is used as the username and password for all oCIS operations during the migration. + +* The oCIS instance should be *fresh and clean* before starting the migration. If the target instance already contains data, it may cause conflicts. +==== + +== Migration Steps + +After the prerequisites are met, the migration can be started. Details for each occ command can be found in the xref:configuration/server/occ_command.adoc#migrate-to-ocis[Migrate to oCIS] occ command reference. + +=== Initialize + +Initialize the migration by pointing to the target oCIS instance. The host and the `--insecure` flag (if used) are stored and reused for all subsequent steps: + +[source,bash] +---- +sudo -u www-data \ + php /var/www/owncloud/occ \ + migrate:to-ocis:init \ + ocis.server.example +---- + +Use `-k` to ignore the SSL certificate of the oCIS instance: + +[source,bash] +---- +sudo -u www-data \ + php /var/www/owncloud/occ \ + migrate:to-ocis:init -k \ + ocis.server.example +---- + +Use `-f` to reset a previous migration and start from the beginning. Ensure the target oCIS instance is clean before resetting: + +[source,bash] +---- +sudo -u www-data \ + php /var/www/owncloud/occ \ + migrate:to-ocis:init -f \ + ocis.server.example +---- + +=== Verify + +Verify that the OC10 installation is ready for migration. This checks that all enabled users have valid, non-duplicate email addresses: + +[source,bash] +---- +sudo -u www-data \ + php /var/www/owncloud/occ \ + migrate:to-ocis:verify +---- + +Disabled users will be shown in the verification output but will not stop the migration. If a disabled user needs to be migrated, enable them before running this step — or reset the migration and re-verify. + +You can skip this step with `--skip`, but you take full responsibility for any email-related problems during migration. + +=== Migrate Users + +Migrate the OC10 users to oCIS. The admin password is asked interactively: + +[source,bash] +---- +sudo -u www-data \ + php /var/www/owncloud/occ \ + migrate:to-ocis:migrate:users admin +---- + +New users are created in oCIS to match the OC10 users. If a user already exists in oCIS (for example the `admin` account), the existing account will be reused. + +=== Assign a Role + +Assign a role to all migrated users. Available roles are fetched from the oCIS instance and the role to assign is selected interactively: + +[source,bash] +---- +sudo -u www-data \ + php /var/www/owncloud/occ \ + migrate:to-ocis:assign-role admin +---- + +The same role is assigned to all migrated OC10 users, except the oCIS admin. OC10 roles are not preserved during migration — all users receive a single role regardless of their original OC10 role. For most installations the `User` role is the appropriate choice. + +NOTE: OC10 admin users who are members of the OC10 `admin` group will have that group membership migrated to oCIS, but they will not receive oCIS admin privileges unless the assigned role grants them. The oCIS admin must manually set the appropriate oCIS role for any user that should have elevated permissions after migration. + +OC10 subadmin privileges have no equivalent role in oCIS and are not migrated. + +This step is mandatory and cannot be skipped. + +=== Migrate Groups + +Migrate the OC10 groups and their user memberships to oCIS. The admin password is asked interactively: + +[source,bash] +---- +sudo -u www-data \ + php /var/www/owncloud/occ \ + migrate:to-ocis:migrate:groups admin +---- + +If a group already exists in oCIS, the existing group will be reused. Users not found in oCIS (for example because they were disabled and not migrated) will be skipped, but this will not stop the migration. + +=== Migrate Files + +Migrate each user's files to oCIS using the rclone binary bundled with the app. oCIS impersonation is used to access each user's account. The admin password is asked interactively: + +[source,bash] +---- +sudo -u www-data \ + php /var/www/owncloud/occ \ + migrate:to-ocis:migrate:files admin +---- + +Each user's home directory contents are migrated into that user's *personal Space* in oCIS. External mounts and received shares are excluded — only files owned by the user in their OC10 home are transferred. + +The following users are skipped and will not cause the migration to stop: + +* Users that have never logged in (they have no files to migrate). +* Users not found in oCIS (typically disabled users that were not migrated). + +=== Migrate Shares + +Migrate all user shares, group shares, and link shares. oCIS impersonation is used to access each user's account. The admin password is asked interactively: + +[source,bash] +---- +sudo -u www-data \ + php /var/www/owncloud/occ \ + migrate:to-ocis:migrate:shares admin +---- + +The same users are skipped as in the file migration step. The following share errors will be reported but will not stop the migration: + +* Shares pointing to missing users or groups (that were not migrated). +* Link shares that fail due to password restrictions. + +For password-protected link shares: the share will be migrated with a new password that does not match the original OC10 password. Users should change the passwords of all their share links after migration. + +== Migration with LDAP Users + +If OC10 is connected to an LDAP server, the migration differs slightly: the user and group migration steps are skipped because users and groups come from the LDAP server. Only local (non-LDAP) users and groups are not covered — these must be created manually in oCIS before starting migration, with matching usernames and group names. + +=== OC10 Requirements + +In addition to the regular requirements: + +* LDAP users *must* have the email attribute set (LDAP wizard -> Advanced tab -> Email field; usually `mail`). +* The username attribute should be set to the `uid` or `samAccountName` attribute. By default, the internal username attribute (usually `entryUUID` / `objectGUID`) is used, which is typically incorrect for migration. + +Run the following to change the attribute to `uid` and re-sync users afterwards: ++ +[source,bash] +---- +sudo -u www-data \ + php /var/www/owncloud/occ \ + ldap:set-config '' ldapUserName uid +---- + +=== oCIS Requirements + +In addition to the auth-app requirements, verify the following oCIS environment variables: + +* `OCIS_LDAP_USER_ENABLED_ATTRIBUTE` must exist and not be false. The default value uses the ownCloud schema which is unlikely to be present in your LDAP. +* `OCIS_LDAP_USER_SCHEMA_ID` and `OCIS_LDAP_GROUP_SCHEMA_ID` should be set appropriately (for example `entryUUID`). +* `OCIS_ADMIN_USER_ID` must match the configured `OCIS_LDAP_USER_SCHEMA_ID` value for the LDAP user acting as admin. + +The following serves as a configuration template: + +[source,plaintext] +---- +OCIS_LDAP_INSECURE: "true" + +OCIS_LDAP_URI: ldap://10.0.2.27:14141 +OCIS_LDAP_BIND_DN: "cn=admin,dc=owncloudqa,dc=com" +OCIS_LDAP_BIND_PASSWORD: owncloud123 + +OCIS_LDAP_GROUP_BASE_DN: "ou=groups,dc=owncloudqa,dc=com" +OCIS_LDAP_GROUP_FILTER: "(objectclass=groupOfNames)" +OCIS_LDAP_GROUP_OBJECTCLASS: "groupOfNames" + +OCIS_LDAP_USER_BASE_DN: "ou=people,dc=owncloudqa,dc=com" +OCIS_LDAP_USER_FILTER: "(objectclass=inetOrgPerson)" +OCIS_LDAP_USER_OBJECTCLASS: "inetOrgPerson" + +OCIS_LDAP_USER_ENABLED_ATTRIBUTE: "employeeType" +IDP_LDAP_LOGIN_ATTRIBUTE: "uid" + +OCIS_LDAP_GROUP_SCHEMA_ID: "entryUUID" +OCIS_LDAP_USER_SCHEMA_ID: "entryUUID" +OCIS_ADMIN_USER_ID: "a73c6ea6-6e7c-103f-8110-dd19ecb0bb36" +---- + +Verify LDAP access is working before starting the migration by logging in with some LDAP users. + +=== Migration Steps for LDAP + +The migration steps for LDAP are the same as for regular migration, except that user and group migration are skipped: + +[source,bash] +---- +sudo -u www-data php /var/www/owncloud/occ migrate:to-ocis:init -k ocis.server.example +sudo -u www-data php /var/www/owncloud/occ migrate:to-ocis:verify +sudo -u www-data php /var/www/owncloud/occ migrate:to-ocis:migrate:users --skip admin +sudo -u www-data php /var/www/owncloud/occ migrate:to-ocis:assign-role admin +sudo -u www-data php /var/www/owncloud/occ migrate:to-ocis:migrate:groups --skip admin +sudo -u www-data php /var/www/owncloud/occ migrate:to-ocis:migrate:files admin +sudo -u www-data php /var/www/owncloud/occ migrate:to-ocis:migrate:shares admin +---- + +Only LDAP users (and any manually created users) will have their files and shares migrated. diff --git a/modules/admin_manual/partials/nav.adoc b/modules/admin_manual/partials/nav.adoc index 3ca238b18..065e4c353 100644 --- a/modules/admin_manual/partials/nav.adoc +++ b/modules/admin_manual/partials/nav.adoc @@ -138,6 +138,7 @@ **** xref:admin_manual:maintenance/encryption/migrating-from-user-key-to-master-key.adoc[Migrating from User Key to Master Key Encryption] *** xref:admin_manual:maintenance/migrating.adoc[Migrating to a Different Server] *** xref:admin_manual:maintenance/migrating_to_kiteworks.adoc[Migrating to Kiteworks PDN] +*** xref:admin_manual:maintenance/migrating_to_ocis.adoc[Migrating to ownCloud Infinite Scale] ** Enterprise *** Authentication