Service Independent CLI

This document describes ocis CLI commands that are service independent.

For service dependent CLI commands, see the following services:

Common Parameters

The ocis package offers a variety of CLI commands for monitoring or repairing ocis installations. Most of these commands have common parameters such as:

--help (or -h)
Use to print all available options.

--basePath (or -p)
Needs to point to a storage provider, paths can vary depending on your ocis installation. Example paths are:

.ocis/storage/users          # bare metal installation
/var/tmp/ocis/storage/users  # docker installation
...

--dry-run
This parameter, when available, defaults to true and must explicitly set to false.
--verbose (or -v)
Get a more verbose output.

List of CLI Commands

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. Empty blobs will not be checked. Can also be switched to s3ng, but needs addtional envvar configuration (see the storage-users service for more details).
--fail
Exits with non-zero exit code if inconsistencies are found. Useful for automation.

Cleanup Orphaned Shares

When a shared space or directory got deleted, use the shares cleanup command to remove those share orphans. This can’t be done automatically at the moment.

ocis shares cleanup

List Unified Roles

This command simplifies the process of finding out which UID belongs to which role. The command using markdown as output format is:

ocis graph list-unified-roles --output-format md

The output of this command includes the following information for each role:

Name
The human readable name of the role.
UID
The unique identifier of the role.
Enabled
Whether the role is enabled or not.
Description
A short description of the role.
Condition
Allowed Resource Actions

Example output (shortned)

#	LABEL	UID	ENABLED	DESCRIPTION	CONDITION	ALLOWED RESOURCE ACTIONS
1	Viewer	b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5	enabled	View and download.	exists @Resource.File	libre.graph/driveItem/path/read
					exists @Resource.Folder	libre.graph/driveItem/quota/read
					exists @Resource.File && @Subject.UserType==“Federated”	libre.graph/driveItem/content/read
					exists @Resource.Folder && @Subject.UserType==“Federated”	libre.graph/driveItem/children/read
						libre.graph/driveItem/deleted/read
						libre.graph/driveItem/basic/read
2	ViewerListGrants	d5041006-ebb3-4b4a-b6a4-7c180ecfb17d	disabled	View, download and show all invite

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 (like 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)
Do not remove any revisions but print 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 the storage-users service for more details).
-v / --verbose
Prints additional information about the revisions that are removed.
--glob-mechanism (default: glob
(advanced) Allows specifying the mechanism to use for globbing. Can be glob, list or workers. In most cases the default glob does not need to be changed. If large spaces need to be purged, list or workers can be used to improve performance at the cost of higher cpu and ram usage. list will spawn 10 threads that list folder contents in parallel. workers will use a special globbing mechanism and multiple threads to achieve the best performance for the highest cost.

Service Health

The service health CLI command allows checking the health status of a service. If there are no issues found, nothing health related will get printed.

ocis <service-name> health

Examples

The collaboration service has been started but not configured and is therefore not in a healthy state:

ocis collaboration health

The WOPI secret has not been set properly in your config for collaboration. Make sure your /root/.ocis/config config contains the proper values (e.g. by using 'ocis init --diff' and applying the patch or setting a value manually in the config/corresponding environment variable).

The antivirus service has not been started, the health check responds accordingly:

ocis antivirus health

{"level":"fatal","service":"antivirus","error":"Get \"http://127.0.0.1:9277/healthz\": dial tcp 127.0.0.1:9277: connect: connection refused","time":"2024-10-28T17:47:54+01:00","message":"Failed to request health check"}

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)
Do not remove any empty folders but print the empty folders that would be removed.