¶ imp1sh Ansible Collection for OpenWrt
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 is being developed actively. It has not been fully tested so please handle with caution.
¶ 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 devices with low effort. It is also suitable for medium sized environments in order to make sure every node is configured the same, for example for wireless.
Make use of Ansible features where you can define 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
- 32 MB Storage
- OpenWrt 22.01 or higher
- with Python3 installed
- 64+ MB, for Restic 512+ MB
¶ Recommencation
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:
- 128/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 clone the git repo because it's more current. 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 a group named allhosts defined within your hosts.ini or hosts.yaml. All nodes need to be part of the group.
If you use ansible_openwrtfirewall your Ansible config needs to contain:
hash_behaviour=merge
¶ 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 defined variables in Ansible on a host or on a group basis. Depending on what level you choose the variable names may differ, depending if you choose to define on host or group basis.
There need 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.
If my collection lacks a feature or you find a bug, open an issue in the git bugtracker.
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_openwrtwifi
- imp1sh.ansible_openwrt.ansible_openwrtwireguard