Skip to content

Commit 9ddf298

Browse files
mmattelmmattel
authored
Merge pull request #11793 from owncloud/update_cli_readme
[docs-only] Update the ocis readme, add/update CLI commands
2 parents 3df2375 + 87be9b2 commit 9ddf298

File tree

2 files changed

+515
-36
lines changed

2 files changed

+515
-36
lines changed

‎ocis/README.md‎

Lines changed: 92 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,22 @@
11
# ocis
22

3-
The ocis package contains the Infinite Scale runtime and the commands for the Infinite Scale CLI.
3+
The ocis package includes the Infinite Scale runtime and commands for the Infinite Scale command-line interface (CLI), which are not bound to a service.
4+
5+
Table of Contents
6+
=================
7+
8+
* [Service Registry](#service-registry)
9+
* [Memory limits](#memory-limits)
10+
* [CLI Commands](#cli-commands)
11+
* [Backup CLI](#backup-cli)
12+
* [Cleanup Orphaned Shares](#cleanup-orphaned-shares)
13+
* [List Unified Roles](#list-unified-roles)
14+
* [Move Stuck Uploads](#move-stuck-uploads)
15+
* [Revisions CLI](#revisions-cli)
16+
* [Service Health](#service-health)
17+
* [Trash CLI](#trash-cli)
18+
19+
<!-- Created by https://github.com/ekalinin/github-markdown-toc -->
420

521
## Service Registry
622

@@ -29,6 +45,8 @@ The ocis package offers a variety of cli commands to monitor or repair ocis inst
2945

3046
These paths can vary depending on your ocis installation.
3147

48+
All commands provide a `-h` / `--help` option. Use to print all available options.
49+
3250
### Backup CLI
3351

3452
The backup command allows inspecting the consistency of an ocis storage:
@@ -67,6 +85,56 @@ When a shared space or directory got deleted, use the `shares cleanup` command t
6785
ocis shares cleanup
6886
```
6987

88+
### List Unified Roles
89+
90+
This command simplifies the process of finding out which UID belongs to which role. The command using markdown as output format is:
91+
92+
```bash
93+
ocis graph list-unified-roles --output-format md
94+
```
95+
96+
The output of this command includes the following information for each role:
97+
98+
* `Name`\
99+
The human readable name of the role.
100+
* `UID`\
101+
The unique identifier of the role.
102+
* `Enabled`\
103+
Whether the role is enabled or not.
104+
* `Description`\
105+
A short description of the role.
106+
* `Condition`
107+
* `Allowed Resource Actions`
108+
109+
**Example output (shortned)**
110+
111+
| # | LABEL | UID | ENABLED | DESCRIPTION | CONDITION | ALLOWED RESOURCE ACTIONS |
112+
|:--:|:--------------------------------:|:------------------------------------:|:--------:|:------------------------------------------------------------------------------------:|:---------------------------------------------------------:|:----------------------------------------:|
113+
| 1 | Viewer | b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5 | enabled | View and download. | exists @Resource.File | libre.graph/driveItem/path/read |
114+
| | | | | | exists @Resource.Folder | libre.graph/driveItem/quota/read |
115+
| | | | | | exists @Resource.File && @Subject.UserType=="Federated" | libre.graph/driveItem/content/read |
116+
| | | | | | exists @Resource.Folder && @Subject.UserType=="Federated" | libre.graph/driveItem/children/read |
117+
| | | | | | | libre.graph/driveItem/deleted/read |
118+
| | | | | | | libre.graph/driveItem/basic/read |
119+
| 2 | ViewerListGrants | d5041006-ebb3-4b4a-b6a4-7c180ecfb17d | disabled | View, download and show all invite
120+
121+
### Move Stuck Uploads
122+
123+
In some cases of saturated disk usage, Infinite Scale metadata may become stuck. This can occur when file metadata is being moved to its final destination after file operations. This issue was primarily seen with shares, where uploaded files could not be accessed. The required filename parameter aligns with Infinite Scale's internal processes and is used to complete the formerly stuck move action.
124+
125+
```bash
126+
ocis shares move-stuck-upload-blobs [--dry-run=false] -p /base/path/storage/users
127+
```
128+
129+
This command provides additional options:
130+
131+
* `--dry-run` (default: `true`)\
132+
Only print found files stuck in transition.\
133+
Note: This is a safety measure. You must specify `--dry-run=false` for the command to be effective.
134+
135+
* `--filename` value (default: "received.json")\
136+
File to move from `uploads/` to share manager metadata `blobs/`
137+
70138
### Revisions CLI
71139

72140
The revisions command allows removing the revisions of files in the storage.
@@ -92,51 +160,39 @@ Prints additional information about the revisions that are removed.
92160
* `--glob-mechanism` (default: `glob`\
93161
(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.
94162

95-
### Trash CLI
163+
### Service Health
96164

97-
The trash cli allows removing empty folders from the trashbin. This should be used to speed up trash bin operations.
165+
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.
98166

99167
```bash
100-
ocis trash purge-empty-dirs -p /base/path/storage/users
168+
ocis <service-name> health
101169
```
102170

103-
This command provides additional options:
171+
**Examples**
104172

105-
* `--dry-run` (default: `true`)\
106-
Do not remove any empty folders but print the empty folders that would be removed.
173+
* The `collaboration` service has been started but not configured and is therefore not in a healthy state:
174+
```bash
175+
ocis collaboration health
176+
177+
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).
178+
```
107179
108-
### List Unified Roles
180+
* The `antivirus` service has not been started, the health check responds accordingly:
181+
```bash
182+
ocis antivirus health
183+
184+
{"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"}
185+
```
186+
187+
### Trash CLI
109188
110-
This command simplifies the process of finding out which UID belongs to which role. The command is:
189+
The trash cli allows removing empty folders from the trashbin. This should be used to speed up trash bin operations.
111190
112191
```bash
113-
ocis graph list-unified-roles
192+
ocis trash purge-empty-dirs -p /base/path/storage/users
114193
```
115194
116-
The output of this command includes the following information for each role:
117-
118-
* `Name`\
119-
The human readable name of the role.
120-
* `UID`\
121-
The unique identifier of the role.
122-
* `Enabled`\
123-
Whether the role is enabled or not.
124-
* `Description`\
125-
A short description of the role.
126-
* `Condition`
127-
* `Allowed Resource Action`
128-
129-
**Example output (shortned)**
195+
This command provides additional options:
130196
131-
```bash
132-
+----------------------------+--------------------------------------+----------+--------------------------------+--------------------------------+------------------------------------------+
133-
| NAME | UID | ENABLED | DESCRIPTION | CONDITION | ALLOWED RESOURCE ACTIONS |
134-
+----------------------------+--------------------------------------+----------+--------------------------------+--------------------------------+------------------------------------------+
135-
| Viewer | b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5 | enabled | View and download. | exists @Resource.File | libre.graph/driveItem/path/read |
136-
| | | | | exists @Resource.Folder | libre.graph/driveItem/quota/read |
137-
| | | | | exists @Resource.File && | libre.graph/driveItem/content/read |
138-
| | | | | @Subject.UserType=="Federated" | libre.graph/driveItem/children/read |
139-
| | | | | exists @Resource.Folder && | libre.graph/driveItem/deleted/read |
140-
| | | | | @Subject.UserType=="Federated" | libre.graph/driveItem/basic/read |
141-
+----------------------------+--------------------------------------+----------+--------------------------------+--------------------------------+------------------------------------------+
142-
```
197+
* `--dry-run` (default: `true`)\
198+
Do not remove any empty folders but print the empty folders that would be removed.

0 commit comments

Comments
 (0)