Migration and Update Guide for 5 to 7

antora.yml

@@ -48,7 +48,7 @@ asciidoc:
 
     # this is the first part of the name for envvars between major versions that will be added or removed
     # example for full name: 4.0.0-5.0.0-added.adoc or 4.0.0-5.0.0-removed.adoc
-    env_var_delta_name: '4.0.0-5.0.0'
+    env_var_delta_name: '5.0.0-7.0.0'
 
     # helm_tab_x will be used to assemble the url (tag) accessing the raw content for helm charts (tag)
     # note that tab 2 always contains the actual release and tab 3 the former

modules/ROOT/pages/depl-examples/bare-metal.adoc

@@ -73,6 +73,21 @@ Note that this URL must resolve to the server running this installation.
 
 === Install and configure the Infinite Scale Binary
 
+[NOTE]
+====
+If you have installed Infinite Scale already but want to upgrade it, do the following steps first:
+
+* xref:stopping-infinite-scale[Stop infinite Scale]: +
+You cannot overwrite the binary of a running instance.
+
+* Make a copy of the existing binary first:
++
+[source,bash,subs="attributes+"]
+----
+sudo cp {ocis_bin}/ocis {ocis_bin}/ocis.old
+----
+====
+
 * Download and install the Infinite Scale binary. To get the stable binary from ownCloud, visit {ocis-downloadpage-url}/{download-type}/?sort=time&order=desc[download.owncloud.com,window=_blank], select the version and the platform of choice and copy the link of the file.
 +
 [source,bash,subs="attributes+"]

modules/ROOT/pages/depl-examples/minimal-bare-metal.adoc

@@ -85,6 +85,21 @@ Congratulations, you now have access to your Infinite Scale instance.
 
 == Installation
 
+[NOTE]
+====
+If you have installed Infinite Scale already but want to upgrade it, do the following steps first:
+
+* xref:stopping-infinite-scale[Stop infinite Scale]: +
+You cannot overwrite the binary of a running instance.
+
+* Make a copy of the existing binary first:
++
+[source,bash,subs="attributes+"]
+----
+sudo cp {ocis_bin}/ocis {ocis_bin}/ocis.old
+----
+====
+
 * To get the stable binary from ownCloud, visit {ocis-downloadpage-url}/{download-type}/?sort=time&order=desc[download.owncloud.com,window=_blank], select the version and the platform of choice and copy the link of the file. Check the sort order on the modification date to get the most recent releases on top. Depending on your system and preferences, you may want to save the binary in `{ocis_bin}`.
 +
 --

modules/ROOT/pages/deployment/general/general-info.adoc

@@ -622,13 +622,15 @@ An admin user will be created when running the `ocis init` command with the foll
 
 Login to the webinterface with this admin user and change relevant data according your needs or create new users. As an example to reach out the webinterface use `\https://localhost:9200`.
 
-=== Password Reset for the Admin User
+=== Password Reset for IDM Users
 
 The admin password can be reset via command line if it has been forgotten and the admin can't enter the webUI anymore. Note that the admin user must already exist which happens if you have xref:deployment/general/ocis-init.adoc[initialized Infinite Scale].
 
-After running the respective command and entering a new password, the admin can relogin using the new password.
+See the command below for details and options.
+
+After running the respective command and entering a new password, the admin or user can relogin using the new password.
 
-Note that when Infinite Scale gets initialized with xref:deployment/general/ocis-init.adoc[The ocis init Command], an admin password is created and stored in the `ocis.yaml` file. The lifespan of this admin password is up to the point when it either gets changed in the webUI or via the resetpassword command. Any admin password changes are NOT written back to the `ocis.yaml` file nor manual changes to the `admin_password` are considered as a new password.
+Note that when Infinite Scale gets initialized with xref:deployment/general/ocis-init.adoc[The ocis init Command], an admin password is created and stored in the `ocis.yaml` file. The lifespan of this admin password is up to the point when it either gets changed in the webUI or via the resetpassword command. Any admin password changes are *NOT* written back to the `ocis.yaml` file nor manual changes to the `admin_password` are considered as a new password.
 
 [source,yaml]
 ----
@@ -657,7 +659,7 @@ When the prerequisite from the note above is fulfilled, you can reset the admin
 
 ==== Binary Setup
 
-Run the following command to reset the admin password:
+Run the following command to reset the admin password, use `--user-name <user>` for ordinary users:
 
 [source,bash]
 ----

modules/ROOT/pages/deployment/services/env-var-changes.adoc

@@ -1,9 +1,9 @@
 # Changed Environment Variables in Versions
 :toc: right
-:description: This page contains tables with added and removed environment variables between Infinite Scale version 4.0.0 and 5.0.0.
+:description: This page contains tables with added and removed environment variables between Infinite Scale version 5.0.x and 7.0.0.
 
 :source_path: {ocis_services_raw_url}{service_url_component}{ocis_services_final_path}adoc/env-var-deltas/
-// https://raw.githubusercontent.com/owncloud/ocis/docs-stable-5.0/services/_includes/adoc/env-var-deltas/
+// https://raw.githubusercontent.com/owncloud/ocis/docs-stable-7.0/services/_includes/adoc/env-var-deltas/
 
 == Introduction
 
@@ -23,4 +23,9 @@ Removed::
 --
 include::{source_path}{env_var_delta_name}-removed.adoc[]
 --
+Deprecated::
++
+--
+include::{source_path}{env_var_delta_name}-deprecated.adoc[]
+--
 ====

modules/ROOT/pages/deployment/services/s-list/postprocessing.adoc

@@ -63,39 +63,73 @@ The backoff behavior as mentioned in the `retry` outcome can be configured using
 
 === Resume Post-Processing
 
-If post-processing fails in one step due to an unforeseen error, current uploads will not be retried automatically. A system administrator can instead run CLI commands to retry the failed upload which is a two step process. For details on the `storage-users` command see the xref:{s-path}/storage-users.adoc#manage-unfinished-uploads[Manage Unfinished Uploads] documentation.
+[NOTE]
+====
+If not noted otherwise, commands with the `restart` option can also use the `resume` option. This changes behaviour slightly.
 
-* First list ongoing upload sessions:
+* `restart` +
+When restarting an upload, all steps for open items will be restarted, except if otherwise defined.
+* `resume` +
+When resuming an upload, processing will continue unfinished items from their last completed step.
+====
+
+If post-processing fails in one step due to an unforeseen error, current uploads will not be resumed automatically. A system administrator can instead run CLI commands to resume the failed upload manually which is at minimum a two step process.
+
+NOTE: For details on the `storage-users` command which provides many options see the xref:{s-path}/storage-users.adoc#manage-unfinished-uploads[Manage Unfinished Uploads] documentation.
+
+Depending if you want to restart/resume all or defined failed uploads, different commands are used.
+
+* First, list ongoing upload sessions to identify possibly failed ones. +
+Note that there never can be a clear identification of a failed upload session due to various reasons causing them. You need to apply more critera like free space on disk, a failed service like antivirus etc. to declare an upload as failed.
 +
 [source,bash]
 ----
 ocis storage-users uploads sessions
 ----
 
-* If you want to restart *all* uploads, just rerun the command with the `--restart` flag:
+{empty}
+
+* *All failed uploads*
 +
+--
+If you want to restart/resume all failed uploads, just rerun the command with the relevant flag. Note that this is the preferred command to handle failed processing steps:
+
 [source,bash]
 ----
-ocis storage-users uploads sessions --restart
+ocis storage-users uploads sessions --resume
 ----
+{empty}
+--
 
-* If you want to restart *only one* upload, use the postprocessing restart command with the ID selected:
+* *Particular failed uploads* +
+Use the `postprocessing` command to resume defined failed uploads. For postprocessing steps, the default is to resume . Note that at the moment, `resume` is an alias for `restart` to keep old functionality. `restart` is subject of change and will most likely be removed in a later version.
+
+** *Defined by ID*
 +
+--
+If you want to resume only a specific upload, use the postprocessing resume command with the ID selected:
+
 [source,bash]
 ----
-ocis postprocessing restart -u <uploadID>
+ocis postprocessing resume -u <uploadID>
 ----
+{empty}
+--
 
-Alternatively, instead of starting one specific upload, a system admin can also restart all uploads that are currently in a specific step.
+** *Defined by step*
++
+--
+Alternatively, instead of restarting one specific upload, a system admin can also resume all uploads that are currently in a specific step.
 
 Examples:
 
 [source,bash]
 ----
-ocis postprocessing restart                # Restarts all uploads where postprocessing is finished, but upload is not finished.
-ocis postprocessing restart -s "finished"  # Equivalent to the above.
-ocis postprocessing restart -s "virusscan" # Restart all uploads currently in virusscan step.
+ocis postprocessing resume                # Resumes all uploads where postprocessing is finished, but upload is not finished.
+ocis postprocessing resume -s "finished"  # Equivalent to the above.
+ocis postprocessing resume -s "virusscan" # Resume all uploads currently in virusscan step.
 ----
+--
 
 == Storing
 

modules/ROOT/pages/deployment/services/s-list/storage-users.adoc

@@ -23,7 +23,7 @@ IMPORTANT: The graceful shutdown period is only applicable if the `storage-users
 
 When hard-stopping Infinite Scale, for example with the `kill <pid>` command (SIGKILL), it is possible and likely that not all data from the decomposedfs (metadata) has been written to the storage which may result in an inconsistent decomposedfs. When gracefully shutting down Infinite Scale, using a command like SIGTERM, the process will no longer accept any write requests from _other_ services and will try to write the internal open  requests which can take an undefined duration based on many factors. To mitigate that situation, the following things have been implemented:
 
-*   With the value of the environment variable `STORAGE_USERS_GRACEFUL_SHUTDOWN_TIMEOUT`, the `storage-users` service will delay its shutdown giving it time to finalize writing necessary data. This delay can be necessary if there is a lot of data to be saved and/or if storage access/thruput is slow. In such a case you would receive an error log entry informing you that not all data could be saved in time. To prevent such occurrences, you must increase the default value.
+*   With the value of the environment variable `STORAGE_USERS_GRACEFUL_SHUTDOWN_TIMEOUT`, the `storage-users` service will delay its shutdown giving it time to finalize writing necessary data. This delay can be necessary if there is a lot of data to be saved and/or if storage access/throughput is slow. In such a case you would receive an error log entry informing you that not all data could be saved in time. To prevent such occurrences, you must increase the default value.
 
 *   If a shutdown error has been logged, the command-line maintenance tool xref:maintenance/commands/commands.adoc#inspect-and-manipulate-node-metadata[Inspect and Manipulate Node Metadata] can help to fix the issue. Please contact support for details. 
 
@@ -69,22 +69,30 @@ ocis storage-users uploads <command>
 ----
 COMMANDS:
    sessions  Print a list of upload sessions
-   clean     Clean up leftovers from expired uploads (deprecated, do not use it)
-   list      Print a list of all incomplete uploads  (deprecated, do not use it)
 ----
 --
 
 ==== Sessions command
 
-The `sessions` command is the entry point for listing, restarting and cleaning unfinished uploads.
+The `sessions` command is the entry point for listing, restarting/resuming and cleaning unfinished uploads.
+
+NOTE: There can never be a clear identification of a failed upload session due to various reasons causing them. You need to apply more critera like free space on disk, a failed service like antivirus etc. to declare an upload as failed.
+
+[NOTE]
+====
+If not noted otherwise, the `restart` option can also be replaced the `resume` option. This changes behaviour slightly.
+
+* `restart` +
+When restarting an upload, all steps for open items will be restarted, except if otherwise defined.
+* `resume` +
+When resuming an upload, processing will continue unfinished items from their last completed step.
+====
 
 [source,bash]
 ----
 ocis storage-users uploads sessions
 ----
 
-Note, though possible, do not use the deprecated upload commands listed above. Their function has been embedded in the session command as command options.
-
 [source,plaintext]
 ----
 NAME:
@@ -100,6 +108,7 @@ OPTIONS:
    --has-virus   filter sessions by virus scan result (default: unset)
    --json        output as json                       (default: false)
    --restart     send restart event for all listed sessions (default: false)
+   --resume      send resume event for all listed sessions (default: false)
    --clean       remove uploads                       (default: false)
    --help, -h    show help
 ----
@@ -165,7 +174,7 @@ ocis storage-users uploads sessions --expired=false --processing=false
 |
 |===
 
-The sessions command can also clear and restart uploads. The output is the same as if run without the `--clean` or `--restart` flag. Note that it is recommended to run the command first without the `--clean` (`--processing`) flag to double check which uploads get cleaned (restarted).
+The sessions command can also clear and restart/resume uploads. The output is the same as if run without the `--clean` or `--restart/--resume` option. Note that it is recommended to run the command first without the `--clean` (`--processing`) option to double check which uploads would get cleaned (restarted/resumed).
 
 .Cleans all expired uploads regardless of processing and virus state.
 [source,bash]
@@ -175,13 +184,13 @@ ocis storage-users uploads sessions \
      --clean
 ----
 
-.Restarts all uploads that are processing and are not virus infected
+.Resume all uploads that are currently processing and are not virus infected
 [source,bash]
 ----
 ocis storage-users uploads sessions \
      --processing=false \
      --has-virus=false \
-     --restart
+     --resume
 ----
 
 === Manage Trash-Bin Items

modules/ROOT/pages/maintenance/commands/changed-cli.adoc

@@ -0,0 +1,37 @@
+= Changed or Added CLI Commands
+:toc: right
+:description: This page contains a list with added, changed or removed CLI commands between Infinite Scale version 5.0.x and 7.0.0.
+
+== Introduction
+
+{description}
+
+== Affected CLI Commands
+
+See the link for a detailed description of the respective CLI command if available.
+
+* xref:maintenance/commands/commands.adoc#manage-expired-uploads[Manage Expired Uploads]  +
+The `ocis storage-users uploads sessions --restart` command got an alternative `--resume` option. +
+Resume can be used in the same way as restart with a slighly different behavior change.
+
+* xref:maintenance/commands/commands.adoc#purge-expired-space-trash-bin-items[Purge Expired Space Trash-Bin Items]  +
+The `ocis storage-users uploads` got restructured. +
+The deprecated `list` option is now removed, the `clean` option is now part of the `sessions command`.
+
+* xref:maintenance/commands/commands.adoc#resume-post-processing[Resume Post-Processing]  +
+The `ocis postprocessing restart` command got an alternative `resume` option. +
+Resume can be used in the same way as restart with a slighly different behavior change.
+
+* xref:maintenance/commands/commands.adoc#reset-password-for-idm-users[Reset Password for IDM Users] +
+The `ocis idm resetpassword` can now specify the user name via the `--user-name` (`-u`) flag.
+
+* xref:maintenance/commands/commands.adoc#revisions-cleanup[Revisions Cleanup] +
+The `ocis revisions purge` command allows removing revisions of files in the storage. Note that this command has also been backported to version 5 available with its latest release.
+
+* xref:maintenance/commands/commands.adoc#service-health[Service Health] +
+A `health` command has been added to each service: `ocis <service-name> health`.
+
+* xref:maintenance/commands/commands.adoc#trash-purge[Trash Purge]. +
+The `ocis trash purge-empty-dirs` command allows removing empty folders from the trashbin.
+
+* The `ocis graph list-unified-roles` command simplifies the process of finding out which UID belongs to which role. Note that this command is described in the https://github.com/owncloud/ocis/tree/master/ocis#list-unified-roles[ocis repository, window=_blank] and has been added for completeness only.