Ansible Role: openwrt

Overview

This role allows you to manage OpenWRT and its variations using Ansible, without needing Python.

When you add a host to the openwrt inventory group, some Ansible modules are replaced with shell versions that work on standard OpenWRT setups, while keeping most original features. Hosts that are not in this group will not be affected, enabling you to mix tasks for OpenWRT and other platforms. New OpenWRT-specific modules (like uci) are also included. Note: Not all argument combinations have been tested! Some just have been converted from Python for completeness.

Supported Modules

The following modules are currently available:

• command
• copy
• fetch (implicit)
• file
• lineinfile
• nohup (new)
• opkg
• ping
• service
• setup
• shell (implicit)
• slurp
• stat
• sysctl
• template (implicit)
• uci (new)
• wait_for_connection (implicit)

To achieve this, some adjustments are made (referred to as vars_plugins).

Compatibility

This role has been successfully tested with:

• LEDE 17.01 (manually)
• OpenWRT 18.06
• OpenWRT 19.07
• OpenWRT 21.02
• OpenWRT 22.03

Requirements

Some modules may need commands to create SHA1 hashes or encode data in Base64. For Base64, a slow workaround using hexdump | awk is included. There isn't a workaround for SHA1. Modules will look for usable commands for SHA1 (sha1sum, openssl) and Base64 (base64, openssl). If no commands are found, most functions still work, but for example, the fetch module will require validate_checksum: no, always download the file, and indicate changed: yes. Therefore, it's recommended to install coreutils-sha1sum and coreutils-base64 if they are not already provided by busybox. By default, this role installs them automatically.

Role Variables

• openwrt_install_recommended_packages: Checks for commands and installs missing packages (default: yes).

• openwrt_scp_if_ssh: Choose whether to use scp or sftp for OpenWRT systems. Options are yes, no, or smart. The role defaults to yes since OpenWRT does not support sftp by default (default: yes).

• openwrt_remote_tmp: Sets Ansibles remote_temp for OpenWRT systems, defaults to /tmp to minimize flash wear (default: /tmp).

• openwrt_wait_for_connection & openwrt_wait_for_connection_timeout: Indicates whether to wait for the host and for how long (default: yes; timeout: 300 seconds) after a network or Wi-Fi restart.

• openwrt_ssh, openwrt_scp, openwrt_ssh_host, openwrt_ssh_user, openwrt_user_host: Shortcuts for running commands.

Example Playbook

Inventory:

[aps]
ap1.example.com
ap2.example.com
ap3.example.com

[routers]
router1.example.com

[openwrt:children]
aps
routers

Playbook:

- hosts: openwrt
  roles:
    - gekmihesg.openwrt
  tasks:
    - name: copy openwrt image
      command: "{{ openwrt_scp }} image.bin {{ openwrt_user_host|quote }}:/tmp/sysupgrade.bin"
      delegate_to: localhost
    - name: start sysupgrade
      nohup:
        command: sysupgrade -q /tmp/sysupgrade.bin
    - name: wait for reboot
      wait_for_connection:
        timeout: 300
        delay: 60
    - name: install mdns
      opkg:
        name: mdns
        state: present
    - name: enable and start mdns
      service:
        name: mdns
        state: started
        enabled: yes
    - name: copy authorized keys
      copy:
        src: authorized_keys
        dest: /etc/dropbear/authorized_keys
    - name: revert pending changes
      uci:
        command: revert
    - name: configure wifi device radio0
      uci:
        command: set
        key: wireless.radio0
        value:
          phy: phy0
          type: mac80211
          hwmode: 11g
          channel: auto
    - name: configure wifi interface
      uci:
        command: section
        config: wireless
        type: wifi-iface
        find_by:
          device: radio0
          mode: ap
        value:
          ssid: MySSID
          encryption: psk2+ccmp
          key: very secret
    - name: commit changes
      uci:
        command: commit
      notify: reload wifi

You can run the modules outside of a playbook like this:

$ export ANSIBLE_LIBRARY=~/.ansible/roles/gekmihesg.openwrt/library
$ export ANSIBLE_VARS_PLUGINS=~/.ansible/roles/gekmihesg.openwrt/vars_plugins
$ ansible -i openwrt-hosts -m setup all

License

This role is licensed under the GNU General Public License v3.0 (see https://www.gnu.org/licenses/gpl-3.0.txt).

Developing

Creating custom modules for this framework is straightforward. Modules need to be in a wrapper script that provides functions for parameter parsing, JSON handling, and response generation. Modules must match the pattern openwrt_<module_name>.sh. If the module name isn't one of Ansible's core modules, a <module_name>.py file must also exist. This Python file doesn't need to perform any actions but can include documentation.

Be sure to install the packages from requirements.txt in your virtual environment; then activate the environment and run:

$ molecule test

before committing your changes. Writing tests for your new module is also highly encouraged.