Using occ apps commands

This command reference covers the ownCloud maintained apps commands.

ownCloud’s occ command (ownCloud console) is ownCloud’s command-line interface. You can perform common server operations with occ, including installing and upgrading ownCloud, managing users and groups, encryption, passwords, and LDAP setting.

occ is in the owncloud/ directory; for example /var/www/owncloud on Ubuntu Linux. occ is a PHP script. You must run it as your HTTP user to ensure that your ownCloud files and directories retain the correct permissions.

Please ensure that the app you are going to configure is installed and enabled.

Run occ As Your HTTP User

The HTTP user is different on the various Linux distributions. See strong_perms_label to learn how to find your HTTP user.

  • The HTTP user and group in Debian/Ubuntu is www-data.

  • The HTTP user and group in Fedora/CentOS is apache.

  • The HTTP user and group in Arch Linux is http.

  • The HTTP user in openSUSE is wwwrun, and the HTTP group is www.

If your HTTP server is configured to use a different PHP version than the default (/usr/bin/php), occ should be run with the same version. For example, in CentOS 6.5 with SCL-PHP54 installed, the command looks like this:

sudo -u apache /opt/rh/php54/root/usr/bin/php /var/www/html/owncloud/occ

Example Commands

The following examples are based on Ubuntu.

Running occ with no options lists all commands and options

sudo -u www-data php occ
ownCloud version 10.0.8

Usage:
 command [options] [arguments]

Options

-h, --help Display this help message -q, --quiet Do not output any message -V, --version Display this application version --ansi Force ANSI output --no-ansi Disable ANSI output -n, --no-interaction Do not ask any interactive question --no-warnings Skip global warnings, show command output only -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands: check Check dependencies of the server environment help Displays help for a command list Lists commands status Show some status information upgrade Run upgrade routines after installation of a new release. The release has to be installed before

This is the same as sudo -u www-data php occ list.

General syntax help

Run occ with the -h option for syntax help

sudo -u www-data php occ -h

Display your ownCloud version

sudo -u www-data php occ -V
  ownCloud version 10.0.8

Query your ownCloud server status

sudo -u www-data php occ status
  - installed: true
  - version: 10.0.8.5
  - versionstring: 10.0.8
  - edition: Community

Command syntax help

Get detailed information on individual commands with the help command, like this example for the maintenance:mode command

sudo -u www-data php occ --help maintenance:mode
Usage:
 maintenance:mode [options]

Options

    --on              Enable maintenance mode
    --off             Disable maintenance mode
    --output[=OUTPUT] Output format (plain, json or json_pretty, default is plain) [default: "plain"]
-h, --help            Display this help message
-q, --quiet           Do not output any message
-V, --version         Display this application version
    --ansi            Force ANSI output
    --no-ansi         Disable ANSI output
-n, --no-interaction  Do not ask any interactive question
    --no-warnings     Skip global warnings, show command output only
-v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output,
                      2 for more verbose output and 3 for debug

Options and Arguments

occ has options, commands, and arguments. Commands are required. Options are optional. Arguments can be required or optional. The, generic, syntax is

occ [options] command [arguments]

The status command from above has an option to define the output format. The default is plain text, but it can also be json

sudo -u www-data php occ status --output=json
{"installed":true,"version":"9.0.0.19","versionstring":"9.0.0","edition":""}

or json_pretty

sudo -u www-data php occ status --output=json_pretty
{
   "installed": true,
   "version": "10.0.8.5",
   "versionstring": "10.0.8",
   "edition": "Community"
}

This output option is available on all list and list-like commands, which include status, check, app:list, config:list, encryption:status and encryption:list-modules.

Usage of parameters in Options

In case an option requires parameters, following format should be used for short or long Options forms

The following example command has an option in -p (short) form and --path (long) form.

Parameters for long form options will be written after a blank or equal sign

sudo -u www-data ./occ files:scan --path="user_x/files/folder"

Parameters for short form options will be written either directly after the option or after a blank. Do not use the equal sign as this could be interpreted as part of the parameter.

sudo -u www-data ./occ files:scan -p "user_x/files/folder"

Brute Force Protection

Marketplace URL: Brute-Force Protection

Use these commands to configure the Brute Force Protection app. Parametrisation must be done with the occ config command set. The combination of uid and IP address is used to trigger the ban.

List the Current Settings

sudo -u www-data php occ config:list brute_force_protection

Set the Setting

To set a new value, use the command below and replace <Key> and value <Value> accordingly.

sudo -u www-data php occ config:app:set brute_force_protection <Key> --value=<Value> --update-only

Fail Tolerance [attempts]

Number of wrong attempts to trigger the ban.

Key

brute_force_protection_fail_tolerance

Default

3

Time Treshold [seconds]

Time in which the number of wrong attempts must occur to trigger the ban.

Key

brute_force_protection_time_threshold

Default

60

Ban Period [seconds]

Time how long the ban will be active if triggered.

Key

brute_force_protection_ban_period

Default

300

Data Exporter

This app is only available as a git clone. See the Data Exporter description for more information how to install this app.

Import and export users from one ownCloud instance in to another. The export contains all user-settings, files and shares.

Export User Data

instance:export:user <userId> <exportDirectory>

Arguments:

userId

User to export.

exportDirectory

Path to the directory to export data to.

Import User Data

instance:import:user [options] [--] <importDirectory>

Arguments:

userId

User to export.

importDirectory

Path to the directory to import data from.

Options:

-a [UID]
--as=[UID]

Import the user under a different user id.

Migrate Shares

instance:export:migrate:share <userId> <remoteServer>

Arguments:

userId

The exported userId whose shares we want to migrate.

remoteServer

The remote ownCloud server where the exported user is now, for example "https://myown.server:8080/owncloud".

Calendar

Marketplace URL: Calendar

For commands for managing the calendar, please see the DAV Command section in the occ core command set.

Contacts

Marketplace URL: Contacts

For commands for managing contacts, please see the DAV Command section in the occ core command set.

Anti-Virus

Marketplace URL: Anti-Virus

Use these commands to configure the Anti-Virus app. Parametrisation must be done with the occ config command set.

List the Current Settings

sudo -u www-data php occ config:list files_antivirus

Set the Setting

To set a new value, use the command below and replace <Key> and value <Value> accordingly.

sudo -u www-data php occ config:app:set files_antivirus <Key> --value=<Value> --update-only

Antivirus Mode [string]

Antivirus Configuration.

Key

av_mode

Default

'executable'

Possible Values

'executable'
'daemon'
'socket'

Antivirus Socket [string]

Antivirus Socket.

Key

av_socket

Default

'/var/run/clamav/clamd.ctl'

Antivirus Host [string]

Hostname or IP address of Antivirus Host.

Key

av_host

Default

Antivirus Port [integer]

Port number of Antivirus Host, 1-65535.

Key

av_port

Default

Possible Values

1-65535

Antivirus Command Line Options [string]

Extra command line options (comma-separated).

Key

av_cmd_options

Default

Antivirus Path to Executable [string]

Path to clamscan executable.

Key

av_path

Default

'/usr/bin/clamscan'

Antivirus Maximum Filesize [integer]

File size limit, -1 means no limit.

Key

av_max_file_size

Default

'-1'

Possible Values

'-1'
integer number

Antivirus Maximum Stream Lenth [integer]

Max Stream Length.

Key

av_stream_max_length

Default

'26214400'

Antivirus Action [string]

When infected files were found during a background scan.

Key

av_infected_action

Default

'only_log'

Possible Values

'only_log'
'delete'

Antivirus Scan Process [string]

Define scan process.

Key

av_scan_background

Default

'true'

Possible Values

'true'
'false'

S3 Objectstore

Marketplace URL: S3 Object Storage

List objects, buckets or versions of an object

sudo -u www-data occ s3:list

Arguments:

bucket

Name of the bucket; it`s objects will be listed.

object

Key of the object; it`s versions will be listed.

Create a bucket as necessary to be used

sudo -u www-data occ s3:create-bucket

Arguments:

bucket

Name of the bucket to be created

Options

update-configuration

If the bucket exists the configuration will be updated.

accept-warning

No warning about the usage of this command will be displayed.

LDAP Integration

Marketplace URL: LDAP Integration

ldap
 ldap:check-user               Checks whether a user exists on LDAP.
 ldap:create-empty-config      Creates an empty LDAP configuration
 ldap:delete-config            Deletes an existing LDAP configuration
 ldap:search                   Executes a user or group search
 ldap:set-config               Modifies an LDAP configuration
 ldap:show-config              Shows the LDAP configuration
 ldap:test-config              Tests an LDAP configuration
 ldap:update-group             Update the specified group membership
                               Information stored locally

Search for an LDAP user, using this syntax:

sudo -u www-data php occ ldap:search [--group] [--offset="..."] [--limit="..."] search

Searches match at the beginning of the attribute value only. This example searches for givenNames that start with 'rob':

sudo -u www-data php occ ldap:search "rob"

This will find "robbie", "roberta", and "robin". Broaden the search to find, for example, jeroboam with the asterisk wildcard:

sudo -u www-data php occ ldap:search "*rob"

User search attributes are set with ldap:set-config (below). For example, if your search attributes are givenName and sn you can find users by first name + last name very quickly. For example, you’ll find 'Terri Hanson' by searching for te ha. Trailing whitespace is ignored.

Check if an LDAP user exists. This works only if the ownCloud server is connected to an LDAP server.

sudo -u www-data php occ ldap:check-user robert

ldap:check-user will not run a check when it finds a disabled LDAP connection. This prevents users that exist on disabled LDAP connections from being marked as deleted. If you know for sure that the user you are searching for is not in one of the disabled connections, and exists on an active connection, use the --force option to force it to check all active LDAP connections.

sudo -u www-data php occ ldap:check-user --force robert

ldap:create-empty-config creates an empty LDAP configuration. The first one you create has no configID, like this example:

sudo -u www-data php occ ldap:create-empty-config
  Created new configuration with configID ''

This is a holdover from the early days, when there was no option to create additional configurations. The second, and all subsequent, configurations that you create are automatically assigned IDs.

sudo -u www-data php occ ldap:create-empty-config
   Created new configuration with configID 's01'

Then you can list and view your configurations:

sudo -u www-data php occ ldap:show-config

And view the configuration for a single configID:

sudo -u www-data php occ ldap:show-config s01

ldap:delete-config [configID] deletes an existing LDAP configuration.

sudo -u www-data php occ ldap:delete  s01
Deleted configuration with configID 's01'

The ldap:set-config command is for manipulating configurations, like this example that sets search attributes:

sudo -u www-data php occ ldap:set-config s01 ldapAttributesForUserSearch
"cn;givenname;sn;displayname;mail"

The command takes the following format:

ldap:set-config <configID> <configKey> <configValue>

All of the available keys, along with default values for configValue, are listed in the table below.

Configuration Setting

hasMemberOfFilterSupport

hasPagedResultSupport

homeFolderNamingRule

lastJpegPhotoLookup

0

ldapAgentName

cn=admin,dc=owncloudqa,dc=com

ldapAgentPassword

*

ldapAttributesForGroupSearch

ldapAttributesForUserSearch

ldapBackupHost

ldapBackupPort

ldapBase

dc=owncloudqa,dc=com

ldapBaseGroups

dc=owncloudqa,dc=com

ldapBaseUsers

dc=owncloudqa,dc=com

ldapCacheTTL

600

ldapConfigurationActive

1

ldapDynamicGroupMemberURL

ldapEmailAttribute

ldapExperiencedAdmin

0

ldapExpertUUIDGroupAttr

ldapExpertUUIDUserAttr

ldapExpertUsernameAttr

ldapGroupDisplayName cn

ldapGroupFilter

ldapGroupFilterGroups

ldapGroupFilterMode

0

ldapGroupFilterObjectclass

ldapGroupMemberAssocAttr

uniqueMember

ldapHost

ldap://host

ldapIgnoreNamingRules

ldapLoginFilter

(&objectclass=inetOrgPerson(uid=%uid))

ldapLoginFilterAttributes

ldapLoginFilterEmail

0

ldapLoginFilterMode

0

ldapLoginFilterUsername

1

ldapNestedGroups

0

ldapOverrideMainServer

ldapPagingSize

500

ldapPort

389

ldapQuotaAttribute

ldapQuotaDefault

ldapTLS

0

ldapUserDisplayName

displayName

ldapUserDisplayName2

ldapUserFilter

objectclass=inetOrgPerson

ldapUserFilterGroups

ldapUserFilterMode

0

ldapUserFilterObjectclass

inetOrgPerson

ldapUuidGroupAttribute

auto

ldapUuidUserAttribute

auto

turnOffCertCheck

0

useMemberOfToDetectMembership

1

ldap:test-config tests whether your configuration is correct and can bind to the server.

sudo -u www-data php occ ldap:test-config s01
The configuration is valid and the connection could be established!

ldap:update-group updates the specified group membership information stored locally. The command takes the following format:

ldap:update-group <groupID> <groupID <groupID> ...>

The command allows for running a manual group sync on one or more groups, instead of having to wait for group syncing to occur. If users have been added or removed from these groups in LDAP, ownCloud will update its details. If a group was deleted in LDAP, ownCloud will also delete the local mapping info about this group.

New groups in LDAP won’t be synced with this command. The LDAP TTL configuration (by default 10 minutes) still applies. This means that recently deleted groups from LDAP might be considered as 'active' and might not be deleted in ownCloud immediately.

Configuring the LDAP Refresh Attribute Interval

You can configure the LDAP refresh attribute interval, but not with the ldap commands. Instead, you need to use the config:app:set command, as in the following example, which takes a number of seconds to the --value switch.

sudo -u www-data php occ config:app:set user_ldap updateAttributesInterval --value=7200

In the example above, the interval is being set to 7200 seconds. Assuming the above example was used, the command would output the following:

Config value updateAttributesInterval for app user_ldap set to 7200

If you want to reset (or unset) the setting, then you can use the following command:

sudo -u www-data php occ config:app:delete user_ldap updateAttributesInterval

Market

Marketplace URL: Market

The market commands install, uninstall, list, and upgrade applications from the ownCloud Marketplace.

market
  market:install    Install apps from the marketplace. If already installed and
                    an update is available the update will be installed.
  market:uninstall  Uninstall apps from the marketplace.
  market:list       Lists apps as available on the marketplace.
  market:upgrade    Installs new app versions if available on the marketplace
The user running the update command, which will likely be your webserver user, requires write permission for the /apps respectively apps-external folder.
If they don’t have write permission, the command may report that the update was successful, but it may silently fail.

These commands are not available in single-user (maintenance) mode. For more details please see the Maintenance Commands section in the occ core command set.

Install an Application

Applications can be installed both from the ownCloud Marketplace and from a local file archive.

Install Apps From The Marketplace

To install an application from the Marketplace, you need to supply the app’s id, which can be found in the app’s Marketplace URL. For example, the URL for Two factor backup codes is https://marketplace.owncloud.com/apps/twofactor_backup_codes. So its app id is twofactor_backup_codes.

sudo -u www-data occ market:install <ids> [option]

Arguments:

ids

Ids of the apps

Options

-l [LOCAL]
--local=[LOCAL]

Optional path to a local app package.

Install Apps From a File Archive

To install an application from a local file archive, you need to supply the path to the archive, and that you pass the -l switch. Only zip, gzip, and bzip2 archives are supported.

Usage Example

# Install an app from the marketplace.
sudo -u www-data occ market:install twofactor_backup_codes

# Install an app from a local archive.
sudo -u www-data occ market:install -l /mnt/data/richdocuments-2.0.0.tar.gz

Uninstall an Application

To uninstall an application use the following commands:

sudo -u www-data occ market:uninstall <ids>

Arguments:

ids

Ids of the apps

List Apps From The Marketplace

This command lists apps available on the marketplace. It returns the ids if the apps.

sudo -u www-data occ market:list

Upgrade an Application

Install new app versions if available on the marketplace by using following commands:

sudo -u www-data occ market:upgrade <ids> [options]

Arguments:

ids

Ids of the apps

Options

-l [LOCAL]
--local=[LOCAL]

Optional path to a local app package.

--major

Allow update to a new major version.

Password Policy

Marketplace URL: Password Policy

Command to expire a users password.

Command Description

sudo -u www-data occ user:expire-password <uid> [<expiredate>]

Arguments

uid

User ID.

expiredate

The date and time when a password expires,
e.g. 2019-01-01 14:00:00 CET or -1 days.

The expiry date can be provided using any of PHP’s supported date and time formats.

Options

-a, --all

Will add password expiry to all known users. uid and group option are discarded if the option is provided by user.

-u [UID]
--uid=[UID]

The user’s uid is used.
This option can be used as –uid Alice –uid Bob.

-g [GROUP]
--group=[GROUP]

Add password expiry to user(s) under group(s).
This option can be used as –group foo –group bar to add expiry passwords for users in group foo and bar. If uid option (eg: –uid user1) is passed with group, then uid will also be processed.

If an expiry date is not supplied, the password will expire with immediate effect. This is because the password will be set as being expired 24 hours before the command was run. For example, if the command was run at 2018-07-12 13:15:28 UTC, then the password’s expiry date will be set to 2018-07-11 13:15:28 UTC.

After the command completes, console output, similar to that below, confirms when the user’s password is set to expire.

The password for frank is set to expire on 2018-07-12 13:15:28 UTC.

Command Examples

# The password for user "frank" will be set as being expired 24 hours before the command was run.
sudo -u www-data php occ user:expire-password frank

# Expire the user "frank"'s password in 2 days time.
sudo -u www-data php occ user:expire-password frank '+2 days'

# Expire the user "frank"'s password on the 15th of August 2005, at 15:52:01 in the local timezone.
sudo -u www-data php occ user:expire-password frank '2005-08-15T15:52:01+00:00'

# Expire the user "frank"'s password on the 15th of August 2005, at 15:52:01 UTC.
sudo -u www-data php occ user:expire-password frank '15-Aug-05 15:52:01 UTC'

Caveats

Please be aware of the following implications of enabling or changing the password policy’s "days until user password expires" option.

  • Administrators need to run the occ user:expire-password command to initiate expiry for new users.

  • Passwords will never expire for users who have not changed their initial password, because they do not have a password history. To force password expiration use the occ user:expire-password command.

  • A password expiration date will be set after users change their password for the first time. To force password expiration use the occ user:expire-password command.

  • Passwords changed for the first time, will expire based on the active password policy. If the policy is later changed, it will not update the password’s expiry date to reflect the new setting.

  • Password expiration dates of users where the administrator has run the occ user:expire-password command won’t automatically update to reflect the policy change. In these cases, Administrators need to run the occ user:expire-password command again and supply a new expiry date.

Ransomware Protection (Enterprise Edition only)

Marketplace URL: Ransomware Protection

Use these commands to help users recover from a Ransomware attack. You can find more information about the application in the Ransomware Protection documentation.

Command Description

sudo -u www-data occ ransomguard:scan <timestamp> <user>

Arguments

<timestamp>
<user>

Report all changes in a user’s account, starting from timestamp.

sudo -u www-data occ ransomguard:restore <timestamp> <user>

Arguments

<timestamp>
<user>

Revert all operations in a user account after a point in time.

sudo -u www-data occ ransomguard:lock <user>

Arguments

<user>

Set a user account as read-only for ownCloud and other WebDAV clients when malicious activity is suspected.

sudo -u www-data occ ransomguard:unlock <user>

Arguments

<user>

Unlock a user account after ransomware issues have been resolved.

SAML/SSO Shibboleth Integration (Enterprise Edition only)

Marketplace URL: SAML/SSO Integration

shibboleth:mode sets your Shibboleth mode to notactive, autoprovision, or ssoonly

shibboleth:mode [mode]

Two-factor Authentication

Marketplace URL: 2-Factor Authentication

If a two-factor provider app is enabled, it is enabled for all users by default (though the provider can decide whether or not the user has to pass the challenge). In the case of an user losing access to the second factor (e.g., a lost phone with two-factor SMS verification), the admin can temporarily disable the two-factor check for that user via the occ command:

Command Description

sudo -u www-data php occ twofactor:disable <username>

To re-enable two-factor authentication again, use the following command:

sudo -u www-data php occ twofactor:enable <username>