occ: the command line #

occ is the command-line administration tool of owncloud.online. The file occ sits in the root directory of the installation. It starts the same environment as the web interface and also loads the commands of all enabled apps. So the set of commands is not fixed: it depends on whether the instance is installed, whether it is in maintenance mode, and which apps are enabled.

Running occ #

# list all available commands
sudo -u www-data php8.4 /var/www/owncloud.online/occ list

# help for a single command, with all options
sudo -u www-data php8.4 /var/www/owncloud.online/occ user:add --help

You can run occ from any working directory as long as you give the full path: occ changes to the installation directory by itself. The examples on this page leave out the path for brevity.

occ requires the PHP extension posix and should have pcntl as well. Without posix, occ stops immediately. Without pcntl, occ runs with a warning, but long-running commands cannot be interrupted cleanly.

Permissions: always as the web server user #

Before every run, occ checks whether the calling user is the owner of config/config.php. If not, it stops:

Console has to be executed with the user that owns the file config/config.php

On a standard installation this user is www-data. So always run:

sudo -u www-data php8.4 /var/www/owncloud.online/occ status

Running occ as root is wrong even when it works, for example because config/config.php belongs to root by mistake. Files and directories created during the run (log file, previews, files in the data directory) then belong to root, and the web server can no longer write to them. The same applies to the cron entry, see Background jobs.

Global options #

sudo -u www-data php8.4 occ status --output=json_pretty

Maintenance mode #

occ switches maintenance mode on and off. It writes the system value maintenance to config/config.php:

sudo -u www-data php8.4 occ maintenance:mode --on
sudo -u www-data php8.4 occ maintenance:mode --off

# without an option: show the current state
sudo -u www-data php8.4 occ maintenance:mode

In maintenance mode, occ does not load any apps. Their commands disappear from the list as well. occ prints this notice when it starts:

owncloud.online is in maintenance mode - no app have been loaded

Two other states limit the set of commands in the same way:

• Not installed: Only maintenance:install is available, plus the few commands that do not need an installation (status, check, integrity:*, app:check-code, l10n:createjs).
• Upgrade pending: If the instance reports "owncloud.online or one of the apps require upgrade", the apps are not loaded. You get the same commands as in maintenance mode, so the core commands are still there. The way out is occ upgrade.

Single-user mode (maintenance:singleuser, system value singleuser) is different: the apps stay loaded. occ system:cron stops with "We are in admin only mode, skipping cron", the web interface returns HTTP 503 to accounts outside the admin group, and the WebDAV endpoint rejects every request with "System in single user mode.", including requests from administrators.

Maintenance and upgrades #

To upgrade, install the new code first and then run occ upgrade:

sudo -u www-data php8.4 occ maintenance:mode --on
sudo -u www-data php8.4 occ upgrade
sudo -u www-data php8.4 occ maintenance:mode --off

In the shipped release, integrity:check-core and integrity:check-app check no files and always report success: the core does not enforce the check for the shipped channel, and the release package contains no signatures. How to verify a package instead is described under Integrity check.

This command releases file locks that were left behind after a crash:

# safe while the instance is running: expired locks only
sudo -u www-data php8.4 occ maintenance:file-locks --cleanup-expired

# all locks, requires maintenance mode
sudo -u www-data php8.4 occ maintenance:file-locks --all

With --dry-run the command only shows what it would delete. It works on the database table file_locks. If memcache.locking is set, for example to Redis, the locks live there and the command finds none.

Accounts and groups #

user:sync is the command for connected directory services. Instead of the full class name it accepts the short forms ldap, samba, and shibboleth, and --list shows the active backends:

sudo -u www-data php8.4 occ user:sync --list
sudo -u www-data php8.4 occ user:sync ldap --missing-account-action=disable

--missing-account-action takes disable or remove. remove deletes the account together with its data and files. For regular operation, use disable.

Files and file system #

After every change made directly in the data directory you need files:scan. Otherwise the file cache does not know about the new files:

# one account
sudo -u www-data php8.4 occ files:scan alice

# a subpath only
sudo -u www-data php8.4 occ files:scan --path="/alice/files/Music"

# all accounts
sudo -u www-data php8.4 occ files:scan --all

There are also --group, --unscanned (only files that were not scanned completely), and --repair for detached cache entries. --repair is much slower; run it in a maintenance window.

Shares #

When you transfer an account, its shares move along. files:transfer-ownership handles this, see the previous section.

Configuration #

sudo -u www-data php8.4 occ config:list system
sudo -u www-data php8.4 occ config:system:set loglevel --value 2 --type integer

config:list replaces a fixed set of confidential system values with ***REMOVED SENSITIVE VALUE***. Among them are dbpassword, passwordsalt, secret, mail_smtppassword, ldap_agent_password, marketplace.key, the client secret under openid-connect, and the credentials under redis and objectstore. Only --private prints them in plain text. The command does not filter app values from the database. They appear unchanged in the output of config:list all and config:list <app>, even without --private. Never paste the output into a ticket or a repository without checking it first. The individual keys are described in Configuration (config.php).

Background jobs #

The three background: commands write the same app value core / backgroundjobs_mode; you can read it with config:app:get core backgroundjobs_mode. The recommended mode is cron. Setup and checks are described in Background jobs.

system:cron stops if an upgrade is pending, if maintenance mode or single-user mode is on, or if the execution mode is none. With --progress it shows a progress bar. Never use this option in a crontab entry.

Database #

Back up the database before any of these operations, see Backups and updates. In regular operation you do not call migrations:* directly; occ upgrade takes care of it.

Logging #

# level warning, output to a file
sudo -u www-data php8.4 occ log:manage --level warning
sudo -u www-data php8.4 occ log:owncloud --enable --rotate-size 100M

log:manage writes the system values log_type (owncloud, syslog, or errorlog), loglevel (debug, info, warning, error, fatal), and logtimezone. log:owncloud writes logfile and log_rotate_size (default 104857600; 0 turns rotation off). To read and analyze the log, see Server log and error messages.

Apps #

The four market: commands come from the Market app and are only available while it is enabled. The catalog and its configuration are described in Apps and Marketplace.

In general, an app provides its commands only while it is enabled. After app:disable files_external, all files_external:* commands disappear from occ list.

Other registered command groups #

Details on encryption are in Encryption.

Troubleshooting #