Skip to content

linuxfabrik.lfops.nextcloud_occ_system_config

Manage a Nextcloud system configuration value via occ

Synopsis

  • Drives occ config:system:set and config:system:delete to bring a single system config key into the desired state.
  • The current value is read from occ config:system:get (or from a pre-fetched occ config:list --output=json --private listing passed via installed_config_json). occ config:system:set is only called when the stored value does not already match value.
  • When name contains spaces, each whitespace-separated token is passed as a separate argument to occ, matching how Nextcloud addresses nested keys (e.g. name="trusted_domains 0", name="forbidden_filename_characters 0").
  • Booleans are normalized for occ. value values true/1/on/yes (case-insensitive) become the literal string true; everything else becomes false. This matches what Nextcloud's CastHelper accepts on config:system:set. Note that this differs from nextcloud_occ_app_config, which stores booleans as 1/0.

Available since LFOps 6.0.0.

Requirements

  • A working Nextcloud installation with the occ command available.

Mandatory Parameters

name

  • Configuration key. Multiple whitespace-separated tokens are forwarded as separate arguments to occ, which is how Nextcloud addresses nested keys.
  • Type: String.

Optional Parameters

installed_config_json

  • Pre-fetched output of occ config:list --output=json --private, as either a JSON string or an already-parsed dict. When set, the module skips the config:system:get call and walks name through the dict tree (descending into both dicts and lists by index), which avoids running occ once per key when looping over many keys.
  • Type: Raw.

occ_path

  • Absolute path to the Nextcloud occ command.
  • Type: String.
  • Default: /var/www/html/nextcloud/occ

php_path

  • PHP binary to invoke occ with. A bare php relies on $PATH; pass an absolute path to pin a specific PHP version.
  • Type: String.
  • Default: php

state

  • present creates or updates the key, absent deletes it.
  • Type: String. One of absent, present.
  • Default: present

type

  • Data type occ config:system:set records for the value. Note that occ names the floating point type double, not float.
  • Type: String. One of string, integer, double, boolean.
  • Default: string

value

  • Target value for the configuration key. Required when state=C(present).
  • Type: String.

Examples

- name: 'Set a system configuration value'
  linuxfabrik.lfops.nextcloud_occ_system_config:
    name: 'check_for_working_wellknown_setup'
    value: true
    type: 'boolean'

- name: 'Set an array subkey'
  linuxfabrik.lfops.nextcloud_occ_system_config:
    name: 'forbidden_filename_characters 0'
    value: '*'

Return Values

changed

  • Whether the value had to be changed.
  • Type: Bool.
  • Returned: always.

current_value

  • Stored value (as a string) before any changes were applied. Empty string when the key did not exist. Booleans are returned lowercase (true/false) to match what occ config:system:set accepts.
  • Type: String.
  • Returned: always.

rc

  • Exit code of the occ config:system:set or config:system:delete command.
  • Type: Number.
  • Returned: when changed and not in check mode.

stderr

  • Standard error of the occ config:system:set or config:system:delete command.
  • Type: String.
  • Returned: when changed and not in check mode.

stdout

  • Standard output of the occ config:system:set or config:system:delete command.
  • Type: String.
  • Returned: when changed and not in check mode.

Authors

  • Linuxfabrik GmbH, Zurich, Switzerland, https://www.linuxfabrik.ch