Skip to content
/ ansible_managemynetwork Public

ansible collection with different roles that you can use to manage your network, typically alpine, debian, fedora, freebsd based stuff

License

BSD-3-Clause license
28 stars 4 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

imp1sh/ansible_managemynetwork

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

471 Commits
meta
meta
 
 
plugins
plugins
 
 
roles
roles
 
 
roles_archive
roles_archive
 
 
.gitmodules
.gitmodules
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
galaxy.yml
galaxy.yml
 
 

Repository files navigation

Ansible Managemynetwork Collection (MMN)

This is a collection that is flexible and extensive at the same time. It aims to handle all the tasks that one would want in a complex network environment. Each role only cares about its specific task. So installing packages for example is exclusively done in the packages role and not within others. I try to follow this paradigm throughout all rules, even when I'm not completely there, yet. Another concept I try to follow is that there's always the need to define on a host level and/or on a group level in Ansible. When the role is done right (and currently that's not every role, yet) there are specific variable for defining things on a host or on a group level.

The main Focus will be Debian Linux and OpenWrt. I had been using Alpine and FreeBSD for a long time but the focus will be a more homogenous environment based on mainly Debian. Yet all roles are build so they can be expanded to more OSes very easily. Feel free to make a pull request.

OpenWrt roles were merged from imp1sh.ansible_openwrt into imp1sh.ansible_managemynetwork in December 2023. In the course of the following year of 2024 I will partly merge them further, like zabbix agent. This will soon be merged into one role that can handle normal Linuxes as well as OpenWrt instead of having two seperate roles for that.

This collection will try to support all of those Operating Systems:

  • Debian Linux (main focus)
  • OpenWrt (main focus)
  • FreeBSD (best effort)
  • Ubuntu Linux (best effort)
  • Manjaro/Arch Linux (rarely supported across the roles)
  • Alpine Linux (may work, but basically deprecated)
  • RedHat and Clones (may work, but basically deprecated)

Some roles are and will stay OpenWrt only, like ansible_openwrtfirewall. Others will be united further in the future.

Generally speaking this collection aims to achieve a seperation of logical elements being only in the role. This way all you have to do is call the role. Manual adjustmens to the playbook are very rare. All you do is set your variables and then run the role / collection.

This Collection is quite old. It grew over time and contains LOTS of different roles. Only consider the documented roles to be in a ready for production state. All other roles will be removed or lifted to the same quality standard in the future.

I am working on integrating formerly OpenWrt specific roles into the general roles. Those general roles will work with common Linux distribution but also with OpenWrt.

  • ansible_packages
  • ansible_zabbixagent
  • ansible_restic

OpenWrt specific

The roles starting with ansible_openwrt* are OpenWrt specific.The goal is to be able to manage every aspect of OpenWrt centrally with Ansible.

Advantages of imp1sh OpenWrt roles

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 but it's also well suited for home environments. With it you can manage plenty of Access Points / Firewalls with low effort. Using it will help you dramatically in order to make your device configurations consistent.

Use Ansible properties to your needs, e.g. defining variables once and use them often. This simplifies management fundamentally. At the same time you can access the expandibility and flexibility of OpenWrt and its packages.

Hardware requirements OpenWrt device

The openwrt roles in this collection us python which is not installed on stock OpenWrt. You will need quite a lot of storage so you can install it. 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
  • OpenWrt 23.05
  • 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_managemynetwork

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 containing all hosts. In the docs we typically use the name tags_allhosts defined. {.is-warning}

Using the roles

Use the roles in a playbook by referencing the roles you need, for example:

---
- hosts: manacdev
  roles:
  - imp1sh.ansible_managemynetwork.ansible_openwrtsystem
  - imp1sh.ansible_managemynetwork.ansible_openwrtdropbear
  - imp1sh.ansible_managemynetwork.ansible_openwrtservices
  - imp1sh.ansible_managemynetwork.ansible_openwrtnetwork
  - imp1sh.ansible_managemynetwork.ansible_openwrtfirewall
  - imp1sh.ansible_managemynetwork.ansible_openwrtdhcp

Variables

You can define 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.

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 to the common ansible convention of defning group variable values within the actual group scope we need a more global group containing all hosts like tags_allhosts. The assocition to the group(s) is done via a dict item representing the actual group name. In this example the groups are openwrthosts and openwrtaccesspoints.

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 Varible Prefix
imp1sh.ansible_managemynetwork.ansible_openwrtsystem openwrt_system_*
imp1sh.ansible_managemynetwork.ansible_openwrtdropbear openwrt_dropbear_*
imp1sh.ansible_managemynetwork.ansible_openwrtservices openwrt_services_*
imp1sh.ansible_managemynetwork.ansible_openwrtnetwork openwrt_network_*
imp1sh.ansible_managemynetwork.ansible_openwrtfirewall openwrt_firewall_*
imp1sh.ansible_managemynetwork.ansible_openwrtdhcp openwrt_dhcp_*
imp1sh.ansible_managemynetwork.ansible_openwrtpackages òpenwrt_packages_*
imp1sh.ansible_managemynetwork.ansible_restic openwrt_restic_*
imp1sh.ansible_managemynetwork.ansible_openwrtdhcp openwrt_dhcp_*
imp1sh.ansible_managemynetwork.ansible_openwrtacme openwrt_acme_*

OpenWrt roles 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.

Those are the roles that are purely OpenWrt specific.

About

ansible collection with different roles that you can use to manage your network, typically alpine, debian, fedora, freebsd based stuff

Resources

Readme

License

BSD-3-Clause license
Activity

Stars

28 stars

Watchers

4 watching

Forks

4 forks
Report repository

Releases 28

v0.6.0 Latest
Oct 19, 2024
+ 27 releases

Packages

No packages published

Languages