community.openwrt.uci module – Controls OpenWrt UCI

Note

This module is part of the community.openwrt collection (version 1.11.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.openwrt.

To use it in a playbook, specify: community.openwrt.uci.

Synopsis

• The community.openwrt.uci module controls OpenWrt UCI through the native ucode UCI bindings.

• It supports all the command line functionality plus some extra commands.

Note

This module has a corresponding action plugin.

Parameters

Parameter	Comments
autocommit boolean	Whether to automatically commit changes. Choices: false ← (default) true
command aliases: cmd string	uci command to execute. The default is set if value is passed, otherwise the default is get. The get, export, and show states should be factored out of this module into an _info module. Choices: "absent" "add" "add_list" "batch" "changes" "commit" "del_list" "delete" "ensure" "export" "find" "find_all" "get" "import" "rename" "reorder" "revert" "section" "set" "show"
config string	Config part of the key. If not specified, extracted from key.
find aliases: find_by, search string	Value(s) to match sections against. Option value to find if option is set. May be list. Dict of options/values if option is not set. Values may be list. Lists are compared in order. Required when command=find or command=section.
keep_keys aliases: keep string	Space separated list or list of keys not in value or find to keep when replace=yes.
key string	The uci key to operate on. Takes precedence over config, section and option. If not specified, constructed as config.section.option.
merge boolean	Whether to merge or replace when command=import. Choices: false ← (default) true
name string	New name when command=rename or command=add. Desired name when command=section. If a matching section is found it is renamed, if not it is created with that name.
operations list / elements=dictionary added in community.openwrt 1.9.0	A list of UCI operations to execute in order using one UCI cursor. Each entry accepts the same options as a standalone invocation except operations. Per-operation results are returned in operations. An empty list performs no operations and reports no change. Set top-level autocommit=true to commit all staged changes once after the list succeeds, or include an operation with command=commit.
autocommit boolean	Whether to commit the changes of this operation right after it runs. See autocommit. Choices: false ← (default) true
command aliases: cmd string	See command. Choices: "absent" "add" "add_list" "batch" "changes" "commit" "del_list" "delete" "ensure" "export" "find" "find_all" "get" "import" "rename" "reorder" "revert" "section" "set" "show"
config string	See config.
find aliases: find_by, search string	See find.
keep_keys aliases: keep string	See keep_keys.
key string	See key.
merge boolean	See merge. Choices: false ← (default) true
name string	See name.
option string	See option.
redact_keys list / elements=string	UCI option names whose values must be hidden in the diff of this operation. When set, replaces the top-level redact_keys for this operation. See redact_keys.
replace boolean	See replace. Choices: false ← (default) true
section string	See section.
set_find boolean	See set_find. Choices: false true ← (default)
type string	See type.
unique boolean	See unique. Choices: false ← (default) true
value string	See value.
option string	Option part of the key. If not specified, extracted from key.
redact_keys list / elements=string added in community.openwrt 1.9.0	UCI option names whose values must be hidden in diff output. Changed values are represented by REDACTED-present and REDACTED-wanted; unchanged values are represented by REDACTED. A value set on an individual operations entry overrides this top-level list for that operation. This only affects diffs. command=get, command=show, and command=export still return the values; use the no_log task keyword when reading sensitive values.
replace boolean	When command=set or command=section, whether to delete all options not mentioned in keep_keys, value or find when set_find=true. Choices: false ← (default) true
section string	Section part of the key. If not specified, extracted from key.
set_find boolean	When command=section whether to set the options used to search a matching section in the newly created section when no match was found. Choices: false true ← (default)
type string	Section type for command=section, command=find and command=add. If not specified, defaults to the value of section.
unique boolean	When command=add_list, whether to add the value if it is already contained in the list. Choices: false ← (default) true
value string	The value for various commands.

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: full	Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.
platform	Platform: OpenWrt	Target platform for this module.

Notes

Note

• Since version 1.8.0, command=set, command=ensure and command=section compare the stored value before writing, and report changed=true only when it differs. Earlier versions reported changed=true on every run.

• Starting with version 1.9.0 of this collection, this module is implemented in ucode.

Examples

# Find a section of type wifi-iface with matching name or matching attributes.
# If not found create it and set the attributes from find.
# Unconditionally set the attributes from value and delete all other options.
- community.openwrt.uci:
    command: section
    config: wireless
    type: wifi-iface
    name: ap0
    find:
      device: radio0
      ssid: My SSID
    value:
      encryption: none
    replace: true

# Find a matching wifi-iface and delete it.
- community.openwrt.uci:
    command: absent
    config: wireless
    type: wifi-iface
    find:
      ssid: My SSID broken

# Find a matching wifi-iface and delete the options key and encryption.
- community.openwrt.uci:
    command: absent
    config: wireless
    type: wifi-iface
    find:
      ssid: My SSID public
    value:
      - key
      - encryption

# Commit changes and notify.
- community.openwrt.uci:
    cmd: commit
  notify: restart wifi

# Apply several changes through one UCI cursor and commit once at the end.
- community.openwrt.uci:
    autocommit: true
    operations:
      - command: set
        key: system.@system[0].hostname
        value: my-router
      - command: set
        key: network.lan.ipaddr
        value: 192.168.1.1

# Hide a password in the before/after diff.
- community.openwrt.uci:
    command: set
    key: wireless.default_radio0.key
    value: top-secret
    redact_keys:
      - key

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
changes dictionary	Pending UCI changes. Returned: when command=changes
command string	Command executed. Returned: always Sample: "section"
config string	Config part of key. Returned: when given Sample: "wireless"
diff list / elements=dictionary	UCI state before and after each changed operation, with options from redact_keys hidden. Returned: in diff mode when a supported operation changes state
operations list / elements=dictionary	Result of each entry passed through operations, in execution order. Returned: when operations is given
option string	Option part of key. Returned: when given Sample: "ssid"
result string	Output of the uci command. Returned: always Sample: "cfg12523"
result_list list / elements=string	The list form of result. For command=find_all, this is the list of matching positional section IDs, for example @wifi-iface[0]. Named sections are returned as positional IDs. Returned: when command=get or command=find_all Sample: ["0.pool.ntp.org", "1.pool.ntp.org"]
section string	Section part of key. Returned: when given Sample: "@wifi-iface[0]"

Authors

• Markus Weippert (@gekmihesg)

• Vladimir Ermakov (@vooon)

Collection links

• Issue Tracker
• Repository (Sources)
• Report an issue
• Communication