Using occ apps commands

Note

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.

Run occ As Your HTTP User

The HTTP user is different on the various Linux distributions. See Set Strong Directory Permissions 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

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"

Calendar Commands

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

Contacts Commands

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

S3 Objectstore Commands

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 Commands

Note

These commands are only available when the “LDAP user and group backend” app (user_ldap) is enabled.

These LDAP commands appear only when you have enabled the LDAP app. Then you can run the following LDAP commands with occ:

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.

Note

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

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

Note

The user running the update command, which will likely be your webserver user, requires write permission for the /apps folder. If they don’t have write permission, the command may report that the update was successful, but it may silently fail.

Note

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.

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

Notifications

If you want to send notifications to users or groups use the following command.

notifications
  notifications:generate   Generates a notification.

Options and Arguments:

notifications:generate [-u|--user USER] [-g|--group GROUP] [-l|--link <linktext>] [--] <subject> [<message>]

Options:
  -u --user              User id to whom the notification shall be sent
  -g --group             Group id to whom the notification shall be sent
  -l --link              A link associated with the notification

Arguments:
  subject                The notification subject - maximum 255 characters
  message A more extended message - maximum 4000 characters
  linktext               A link to an HTML page

At least one user or group must be set.

A link can be useful for notifications shown in client apps.

Example:

sudo -u www-data php occ notifications:generate -g Office "Emergeny Alert" "Rebooting in 5min"

Password Policy

Command to expire a users password

sudo -u www-data occ user:expire-password

Arguments:

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

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 The user’s uid is used. This option can be used as –uid “Alice” –uid Bob”
-g, --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

Reports

If you’re working with ownCloud support and need to send them a configuration summary, you can generate it using the configreport:generate command. This command generates the same JSON-based report as the Admin Config Report, which you can access under admin -> Settings -> Admin -> General -> Generate Config Report -> Download ownCloud config report.

From the command-line in the root directory of your ownCloud installation, run it as your webserver user as follows, (assuming your webserver user is www-data):

sudo -u www-data occ configreport:generate

This generates the report and send it to STDOUT. You can optionally pipe the output to a file and then attach it to an email to ownCloud support, by running the following command:

sudo -u www-data occ configreport:generate > generated-config-report.txt

Alternatively, you could generate the report and email it all in one command, by running:

sudo -u www-data occ configreport:generate | mail -s "configuration report" \
    -r <the email address to send from> \
    support@owncloud.com

Note

These commands are not available in single-user (maintenance) mode.

Ransomware Protection

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

Note

Ransomware Protection (which is an Enterprise app) needs to be installed and enabled to be able to use these commands.

occ ransomguard:scan <timestamp> <user>     Report all changes in a user's account, starting from timestamp.
occ ransomguard:restore <timestamp> <user>  Revert all operations in a user account after a point in time.
occ ransomguard:lock <user>                 Set a user account as read-only for ownCloud and other WebDAV
                                            clients when malicious activity is suspected.
occ ransomguard:unlock <user>               Unlock a user account after ransomware issues have been resolved.

Shibboleth Modes (Enterprise Edition only)

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

shibboleth:mode [mode]

Note

These commands are only available when the “Shibboleth user backend” app (user_shibboleth) is enabled.

Two-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:

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

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

sudo -u www-data php occ twofactor:enable <username>
All documentation licensed under the Creative Commons Attribution 3.0 Unported license.