Community OpenWrt Migration Guide

This guide provides the information needed for users migrating from gekmihesg.openwrt role to the community.openwrt collection.

If you are new to community.openwrt and not migrating from gekmihesg.openwrt, you should start with the Community OpenWrt User Guide instead.

Overview

The community.openwrt collection builds upon the foundation of the gekmihesg.openwrt Ansible role, which was maintained by Markus Weippert until 2022. While the core functionality remains similar, there are important changes in structure and usage patterns that you will need to address when migrating your playbooks.

The good news is that both projects share the same approach: they enable you to manage OpenWrt devices without requiring Python on the target systems. All modules are implemented as shell scripts, making them compatible with resource-constrained devices. While the underlying code is largely the same, the collection now provides proper documentation for each module, accessible via ansible-doc or the collection documentation site.

Key Differences

Structure

gekmihesg.openwrt was an Ansible role that you included in your playbooks. It provided modules and handlers as part of the role.

community.openwrt is a full Ansible collection with a defined namespace. It provides:

Multiple modules (community.openwrt.opkg, community.openwrt.uci, etc.)
Multiple roles (community.openwrt.init, community.openwrt.common)
Handlers and plugins organized in a standard collection structure

Installation

gekmihesg.openwrt	community.openwrt
ansible-galaxy install gekmihesg.openwrt	ansible-galaxy collection install community.openwrt

Initialization

Both gekmihesg.openwrt and community.openwrt require you to include an initialization role before using their modules and handlers.

gekmihesg.openwrt	community.openwrt
- hosts: openwrt roles: - gekmihesg.openwrt	- hosts: routers roles: - community.openwrt.init

The initialization role sets up the necessary environment, installs recommended packages, configures variables, and registers handlers.

Note

The gekmihesg.openwrt role required all target hosts to be members of an openwrt group. The community.openwrt collection has no such requirement - you can use any group name or host pattern you prefer.

Namespace

All modules and roles now use the community.openwrt namespace prefix.

gekmihesg.openwrt	community.openwrt
- name: Install package opkg: name: luci state: present	- name: Install package community.openwrt.opkg: name: luci state: present

Migration Steps

Step 1: Install the Collection

First, install the community.openwrt collection:

ansible-galaxy collection install community.openwrt

You can optionally add it to your requirements.yml:

---
collections:
  - name: community.openwrt

Step 2: Update Role References

Replace references to the gekmihesg.openwrt role with community.openwrt.init.

gekmihesg.openwrt	community.openwrt
--- - hosts: openwrt gather_facts: false roles: - gekmihesg.openwrt	--- - hosts: routers gather_facts: false roles: - community.openwrt.init

Step 3: Add Module Namespaces

Update all module calls to include the community.openwrt namespace prefix.

gekmihesg.openwrt

community.openwrt

tasks:
  - name: Gather facts
    setup:

  - name: Install package
    opkg:
      name: luci
      state: present

  - name: Configure UCI
    uci:
      command: set
      key: system.@system[0].hostname
      value: myrouter

  - name: Copy file
    copy:
      src: /path/to/file
      dest: /etc/config/custom

tasks:
  - name: Gather facts
    community.openwrt.setup:

  - name: Install package
    community.openwrt.opkg:
      name: luci
      state: present

  - name: Configure UCI
    community.openwrt.uci:
      command: set
      key: system.@system[0].hostname
      value: myrouter

  - name: Copy file
    community.openwrt.copy:
      src: /path/to/file
      dest: /etc/config/custom

Step 4: Handler References

Handlers references remain the same, just make sure you have included the community.openwrt.init role for them to be available.

- name: Configure wireless
  community.openwrt.uci:
    command: set
    key: wireless.radio0.channel
    value: "6"
  notify: Reload wifi

Note

The names of some handlers that were entirely lower case have been capitalized.

Variables

Most variables remain compatible between gekmihesg.openwrt and community.openwrt. The collection uses the same variable names:

openwrt_scp_if_ssh
openwrt_remote_tmp
openwrt_install_recommended_packages
openwrt_wait_for_connection
openwrt_wait_for_connection_timeout

These variables continue to work as before, so your existing variable definitions in inventory, group_vars, or host_vars should not require changes. They can also be set when including the initialization role, as shown in the complete example below.

Complete Example

Here is a complete before-and-after example to illustrate the migration:

gekmihesg.openwrt

community.openwrt

---
- hosts: openwrt
  gather_facts: false
  roles:
    - role: gekmihesg.openwrt
      vars:
        openwrt_install_recommended_packages: true
  tasks:
    - name: Gather facts
      setup:

    - name: Install packages
      opkg:
        name: "{{ item }}"
        state: present
      loop:
        - luci
        - luci-ssl

    - name: Set hostname
      uci:
        command: set
        key: system.@system[0].hostname
        value: myrouter
      notify: Reload network

---
- hosts: routers
  gather_facts: false
  roles:
    - role: community.openwrt.init
      vars:
        openwrt_install_recommended_packages: true
  tasks:
    - name: Gather facts
      community.openwrt.setup:

    - name: Install packages
      community.openwrt.opkg:
        name: "{{ item }}"
        state: present
      loop:
        - luci
        - luci-ssl

    - name: Set hostname
      community.openwrt.uci:
        command: set
        key: system.@system[0].hostname
        value: myrouter
      notify: Reload network

Testing Your Migration

After updating your playbooks:

Start small: Test with a single device or a small group first
Run in check mode: Use --check to see what would change without making changes
Verify handlers: Ensure handlers are properly notified and executed
Check facts: Verify that community.openwrt.setup returns the expected facts
Monitor logs: Review task output for any unexpected warnings or errors

Troubleshooting

Collection Not Found

If you see errors like could not resolve module/action 'community.openwrt.opkg':

Verify the collection is installed: ansible-galaxy collection list
Check you are using the correct namespace prefix
Ensure your Ansible version meets the minimum requirements (see the collection README)

Module Behavior Differences

While the collection maintains compatibility with the original role’s functionality, some edge cases may behave slightly differently. If you encounter unexpected behavior:

Check the module documentation: ansible-doc community.openwrt.<module_name>
Review the collection’s issue tracker on GitHub

Getting Help

If you encounter issues during migration:

Check the Community OpenWrt User Guide
Review the collection documentation
Join the Ansible forum and use the community-openwrt tag
Visit the GitHub repository
Consider opening an issue if you believe you have found a compatibility problem

Added in version 0.3.0.