Using occ apps commands — ownCloud 10.0.10 Server Administration Manual 10.0.10 documentation

- « Using occ cor...
- Configuring t... »

# 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.

## occ Command Directory

- Run occ As Your HTTP User
- Calendar Commands
- Contacts Commands
- S3 Objectstore Commands
- LDAP Commands
- Market
- Notifications
- Password Policy
- Reports
- Ransomware Protection
- Shibboleth Modes (Enterprise Edition only)
- Two-factor Authentication

## 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 -> Help & Tips -> 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>

- « Using occ cor...
- Configuring t... »