Merge pull request #954 from owncloud/sessions_command_selective_back…

…port

[5.0] only selective backport of session commands

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

@@ -61,7 +61,9 @@ Example cases for expired uploads::
 * If the bandwith is limited and the file to transfer can't be transferred completely before the upload expiration time is reached, the file expires and can't be processed.
 * If the upload was technically successful, but the postprocessing step failed due to an internal error, it will not get further processed. See the procedure in the xref:{s-path}/postprocessing.adoc#resume-post-processing[Resume Post-Processing] documentation for details how to solve this.
 
-There are two commands available to manage unfinished uploads::
+The following commands are available to manage unfinished uploads::
++
+--
 [source,bash]
 ----
 ocis storage-users uploads <command>
@@ -71,7 +73,119 @@ ocis storage-users uploads <command>
 ----
 COMMANDS:
    sessions  Print a list of upload sessions
-   clean     Clean up leftovers from expired uploads
+   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.
+
+[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:
+   ocis storage-users uploads sessions - Print a list of upload sessions
+
+USAGE:
+   ocis storage-users uploads sessions [command options]
+
+OPTIONS:
+   --id value    filter sessions by upload session id (default: unset)
+   --processing  filter sessions by processing status (default: unset)
+   --expired     filter sessions by expired status    (default: unset)
+   --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)
+   --clean       remove uploads                       (default: false)
+   --help, -h    show help
+----
+
+This will always output a list of uploads that match the criteria. See the examples below.
+
+Some additional information on returned information::
+* `Offset` is the number of bytes the server has already received. +
+If `Offset` == `Size` the server has received all bytes of the upload.
+* `Processing` indicates if the uploaded file is currently going through postprocessing.
+* `Scan Date` and `Scan Result` indicate the scanning status. +
+If `Scan Date` is set and `Scan Result` is empty the file is not virus infected.
+
+==== Command Examples
+
+Command to list ongoing upload sessions
+
+[source,bash]
+----
+ocis storage-users uploads sessions --expired=false --processing=false
+----
+
+{empty}
+
+[caption=]
+.Sessions that are not expired:
+[width="100%",cols="~,~,~,~,~,~,~,~,~,~,~",options="header"]
+|===
+| Space
+| Upload Id
+| Name
+| Offset
+| Size
+| Executant
+| Owner
+| Expires
+| Processing
+| Scan Date
+| Scan Result
+
+| f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c
+| 5e387954-7313-4223-a904-bf996da6ec0b
+| foo.txt
+| 0
+| 1234
+| f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c
+| f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c
+| 2024-01-26T13:04:31+01:00
+| false
+| 2024-04-24T11:24:14+02:00
+| infected: virus A
+
+| f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c
+| f066244d-97b2-48e7-a30d-b40fcb60cec6
+| bar.txt
+| 0
+| 4321
+| f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c
+| f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c
+| 2024-01-26T13:18:47+01:00
+| false
+| 2024-04-24T14:38:29+02:00
+|
+|===
+
+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).
+
+.Cleans all expired uploads regardless of processing and virus state.
+[source,bash]
+----
+ocis storage-users uploads sessions \
+     --expired=true \
+     --clean
+----
+
+.Restarts all uploads that are processing and are not virus infected
+[source,bash]
+----
+ocis storage-users uploads sessions \
+     --processing=false \
+     --has-virus=false \
+     --restart
 ----
 
 === Manage Trash-Bin Items

modules/ROOT/pages/maintenance/commands/commands.adoc

@@ -62,15 +62,15 @@ Compared to unfinished uploads which are handled by the system, managing expired
 
 === Purge Expired Space Trash-Bin Items
 
-This command is about purging old trash-bin items of `project` spaces (spaces that have been created manually) and `personal` spaces. See the xref:{s-path}/storage-users.adoc##purge-expired-space-trash-bin-items[Purge Expired Space Trash-Bin Items] section at the _Storage Users_ service for details.
+This command is about purging old trash-bin items of `project` spaces (spaces that have been created manually) and `personal` spaces. See the xref:{s-path}/storage-users.adoc#cli-commands[CLI Commands] section at the _Storage Users_ service for details.
 
 === Reindex a Space for Search
 
 In rare circumstances, it can be necessary to initiate indexing manually for a given space or user. Though the search service handles exception cases automatically, it can happen that the search service was not able to complete indexing due to a dirty shut-down of the service or because of a bug. Re-indexing should *only* be run on explicit request and supervision by ownCloud support. See the xref:{s-path}/search.adoc#manually-trigger-re-indexing-a-space[Manually Trigger Re-Indexing a Space] section at the _Search_ service for details.
 
 === 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 a xref:{s-path}/postprocessing.adoc#resume-post-processing[CLI command] to retry the failed upload.
+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 a xref:{s-path}/postprocessing.adoc#cli-commands[CLI Commands] to retry the failed upload.
 
 === Inspect and Manipulate Node Metadata