¶ imp1sh Ansible Collection for OpenWrt
The OpenWrt collection has been merged into the ManageMyNetwork Collection (MMN). Use MMN collection for OpenWrt from now on!
This docs won't get any more updates, see github repo for most recent version.
This Ansible Collection contains plenty of roles to manage OpenWrt. The goal is that this collection will be able to manage every aspect of OpenWrt centrally with Ansible.
This collection has been tested thorougly, the final release is yet to come.
¶ Advantages of imp1sh Ansible Collection
The roles contained in this collection are pretty powerful. There are even some options that are not accessible through the LUCI Webinterface. In contrast to using LUCI multiple OpenWrt devices can be managed with Ansible centrally. With it you are able to deploy settings individually, on a group basis or even for every device in your environment.
It can be viewed as an alternate solution to OpenWisp. Yet it is more flexible because it's based upon the super powerful Ansible software.
It is targeted towards Service Providers, Hosters or Cloud Providers. With it you can manage plenty of Access Points / Firewalls with low effort. It is also suitable for smaller and medium sized environments in order to make sure every node is configured consistently.
Use Ansible properties to your needs, e.g. defining variables once and use them often. This simplifies management fundamentally. Even the big players like pfSense do not offer a central management for multiple firewalls.
At the same time you can access the expandibility and flexibility of OpenWrt and its packages.
¶ Hardware requirements OpenWrt device
This collection uses python which is not installed on stock OpenWrt. You will need enough memory to get python. Those are the minimum device properties.
¶ Minimum requirements
- 128 MB Storage
- OpenWrt 22.01 or higher
- Python3 installed on the target device
- 128+ MB,for Restic 512+ MB RAM
¶ Recommendation
Depending on your needs the requirements might be higher. Depending on the additional packages you need you will need more disk space. Generally speaking I would recommand a device with:
- 256+ MB Storage
- 512+ MB RAM
¶ Installation
If you're not using Ansible already please take a look at:
- Ansible Quickstart
- Ansible Getting Started.
You need a system acting as Ansible controller in order to deploy the target nodes. You can not use OpenWrt itself to act as the controller. The target nodes must be reachable via network and the Ansible Controller's SSH public key needs to be installed (System - Administration - SSH-Keys). Try to ssh into the node from the controller.
ssh root@<<ip or hostname of the openwrt systems>>
The login must be successful without errors and without asking for a password.
To install the collection you can use the ansible-galaxy command or you clone the git repo.
The preferred method is to install via
ansible-galaxy collection install imp1sh.ansible_openwrt
If you prefer to use the development version use:
To install into the local working directory:
cd << Ansible working directory>>
ansible-galaxy collection install git+https://github.com/imp1sh/ansible_nftwallcollection.git -p .collections
This will install the collection into the default path:
cd <<Ansible working directory>>
ansible-galaxy collection install git+https://github.com/imp1sh/ansible_nftwallcollection.git
The collection expects to have an Ansible group named allhosts defined. All nodes need to be part of the group.
¶ Using the roles
Use the roles in a playbook by referencing the roles you need, for example:
---
- hosts: manacdev
roles:
- imp1sh.ansible_openwrt.ansible_openwrtsystem
- imp1sh.ansible_openwrt.ansible_openwrtdropbear
- imp1sh.ansible_openwrt.ansible_openwrtservices
- imp1sh.ansible_openwrt.ansible_openwrtnetwork
- imp1sh.ansible_openwrt.ansible_openwrtfirewall
- imp1sh.ansible_openwrt.ansible_openwrtdhcp
¶ Variables
You can definee variables in Ansible on a host or on a group basis. The variable type corresponds to the UCI datatype. If it is a list in UCI, it is a list in Ansible.
Depending on what level you choose the variable names may differ, depending if you choose to define on host or group basis.
There need to a group named allhosts. Within its scope you defined several variables.
Example for defining a rule for one specific host:
openwrt_firewall_ruleshost:
"icmp wan to dmz":
src: "WAN"
dest: "DMZ"
proto: "icmp"
target: "ACCEPT"
In contrast you can define packages to be installed on a group basis within ./group_vars/allhosts.yml. This will deploy the packages to all hosts member of the group openwrthosts.
openwrt_packagesinstallgroup:
openwrthosts:
- "acme"
- "acme-dnsapi"
- "coreutils"
- "flashrom"
- "htop"
- "luci-app-acme"
- "luci-app-statistics"
- "luci-app-vnstat2"
- "nmap-full"
- "python3"
- "screen"
- "tcpdump"
- "vim-fuller"
- "vnstat2"
- "vnstati2"
- "zabbix-agentd"
- "zabbix-extra-wifi"
openwrtaccesspoints:
- "ath10k-board-qca988x"
- "ath10k-firmware-qca988x"
- "ath9k-htc-firmware"
- "kmod-ath10k"
- "kmod-ath9k"
- "kmod-ath9k-common"
¶ Naming conventions for variables
Variable names are constructed by using the role name which is at the same time the uci section name. The wildcard part (*) is the subsection within uci for example:
openwrt_system_hostname
Role: imp1sh.ansible_openwrt.ansible_openwrtsystem
Variables: openwrt_system_*
Role: imp1sh.ansible_openwrt.ansible_openwrtdropbear
Variables: openwrt_dropbear_*
Role: imp1sh.ansible_openwrt.ansible_openwrtservices
Variables: openwrt_services_*
Role: imp1sh.ansible_openwrt.ansible_openwrtnetwork
Variables: openwrt_network_*
Role: imp1sh.ansible_openwrt.ansible_openwrtfirewall
Variables: openwrt_firewall_*
Role: imp1sh.ansible_openwrt.ansible_openwrtdhcp
Variables: openwrt_dhcp_*
Role: imp1sh.ansible_openwrt.ansible_openwrtpackages
Variables: òpenwrt_packages_*
Role: imp1sh.ansible_openwrt.ansible_openwrtrestic
Variables: openwrt_restic_*
Role: imp1sh.ansible_openwrt.ansible_openwrtdhcp
Variables: openwrt_dhcp_*
Role: imp1sh.ansible_openwrt.ansible_openwrtacme
Variables: openwrt_acme_*
¶ Roles of this collection
Each role has a specific purpose. You can use them seperately to control specific uci sections. It is desirably though to control the system as a whole with Ansible. If you do, neither make changes manually by command line nor via the webinterface. Changes will be overwritten by Ansible.
If my collection lacks a feature or you find a bug, open an issue in the git bugtracker.
imp1sh.ansible_openwrt.ansible_openwrtacme- imp1sh.ansible_openwrt.ansible_openwrtbabeld
- imp1sh.ansible_openwrt.ansible_openwrtbatmanadv
- imp1sh.ansible_openwrt.ansible_openwrtbmx7
- imp1sh.ansible_openwrt.ansible_openwrtdhcp
- imp1sh.ansible_openwrt.ansible_openwrtdropbear
- imp1sh.ansible_openwrt.ansible_openwrtfirewall
- imp1sh.ansible_openwrt.ansible_openwrtnetwork
- imp1sh.ansible_openwrt.ansible_openwrpackages
- imp1sh.ansible_openwrt.ansible_openwrtrestic
- imp1sh.ansible_openwrt.ansible_openwrtservices
- imp1sh.ansible_openwrt.ansible_openwrtsqm
- imp1sh.ansible_openwrt.ansible_openwrtsystem
- imp1sh.ansible_openwrt.ansible_openwrttinyproxy
- imp1sh.ansible_openwrt.ansible_openwrtuhttpd
- imp1sh.ansible_openwrt.ansible_openwrtwireless
- imp1sh.ansible_openwrt.ansible_openwrtwireguard