From 65586c223309041b4482ef7665a8c1a8481cdf3f Mon Sep 17 00:00:00 2001 From: jkoberg Date: Thu, 4 Jul 2024 14:59:02 +0200 Subject: [PATCH] docu(ocis): document the new commands Signed-off-by: jkoberg --- ocis/README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 57 insertions(+), 1 deletion(-) diff --git a/ocis/README.md b/ocis/README.md index 4bd86c67aae..15ef1e8650a 100644 --- a/ocis/README.md +++ b/ocis/README.md @@ -23,4 +23,60 @@ To authenticate the connection to the etcd registry, you have to set `ETCD_USERN ## Memory limits -oCIS will automatically set the go native `GOMEMLIMIT` to `0.9`. To disable the limit set `AUTOMEMEMLIMIT=off`. For more information take a look at the official [Guide to the Go Garbage Collector](https://go.dev/doc/gc-guide). \ No newline at end of file +oCIS will automatically set the go native `GOMEMLIMIT` to `0.9`. To disable the limit set `AUTOMEMEMLIMIT=off`. For more information take a look at the official [Guide to the Go Garbage Collector](https://go.dev/doc/gc-guide). + +## Cli commands + +The ocis package offers a variety of cli commands to monitor or repair ocis installations. All these commands have a common parameter: `--basePath` (or `-p`). This needs to point to a storage provider. Examples are: +```bash +.ocis/storage/users # bare metal installation +/var/tmp/ocis/storage/users # docker installation +... +``` +This value can vary depending on your ocis installation. + +### Backup Cli + +The backup command allows inspecting the consistency of an ocis storage: +``` +ocis backup consistency -p /base/path/storage/users +``` + +This will check the consistency of the storage and output a list of inconsistencies. Inconsistencies can be: +* Orphaned Blobs: A blob in the blobstore that is not referenced by any file metadata +* Missing Blobs: A blob referenced by file metadata that is not present in the blobstore +* Missing Nodes: A node that is referenced by a symlink but doesn't exist +* Missing Link: A node that is not referenced by any symlink but should be +* Missing Files: A node that is missing essential files (such as the `.mpk` metadata file) +* Missing/Malformed Metadata: A node that doesn't have any (or malformed) metadata + +This command provides additional options: +* `-b`/`--blobstore` allows specifying the blobstore to use. Defaults to `ocis`. If empty blobs will not be checked. Can also be switched to `s3ng` but needs addtional envvar configuration (see storage-users service). +* `--fail` exists with non-zero exit code if inconsistencies are found. Useful for automation. + +### Revisions Cli + +The revisions command allows removing the revisions of files in the storage +``` +ocis revisions purge -p /base/path/storage/users +``` + +It takes the `--resource-id` (or `--r`) parameter which specify the scope of the command: +* An empty string (default) removes all revisions from all spaces. +* A spaceID (e.g. `d419032c-65b9-4f4e-b1e4-0c69a946181d\$44b5a63b-540c-4002-a674-0e9c833bbe49`) removes all revisions in that space. +* A resourceID (e.g. `d419032c-65b9-4f4e-b1e4-0c69a946181d\$44b5a63b-540c-4002-a674-0e9c833bbe49\!e8a73d49-2e00-4322-9f34-9d7f178577b2`) removes all revisions from that specific file. + +This command provides additional options: +* `--dry-run` (default: `true`) does not remove any revisions but prints the revisions that would be removed. +* `-b` / `--blobstore` allows specifying the blobstore to use. Defaults to `ocis`. Can be switched to `s3ng` but needs addtional envvar configuration (see storage-users service). +* `-v` / `--verbose` prints additional information about the revisions that are removed. + +### Trash Cli + +The trash cli allows removing empty folders from the trashbin. This should be used to speed up trash bin operations. +``` +ocis trash purge-empty-dirs -p /base/path/storage/users +``` + +This command provides additional options: +* `--dry-run` (default: `true`) does not remove any empty folders but prints the empty folders that would be removed.