ansible-mikrotik enables network engineers to automate the configuration and management of MikroTik devices. By leveraging Ansible's idempotent execution model, the provided playbooks simplify network operations significantly, minimize manual errors, and streamline deployment in dynamic network environments.
If you want to test this in a lab environment with virtualized MikroTik devices, you can use containerlab environment we have prepared.
Check out the narrowin demo controller for a live demonstration of this repository's capabilities for MikroTik device management and lab environments. This network is fully virtualized and configured with ansible.
- Automated Configuration: Quickly deploy and update MikroTik device settings including interfaces, routing, firewall rules, and VPN configurations.
- Idempotence: Ensure configurations are applied consistently without unintended changes.
- Customizable Variables: Easily override defaults to suit your configuration requirements.
- Modular Design: Clean separation between tasks, defaults, and configuration files for easy maintenance and extension.
- Dynamic Inventory Support: Integrate with your existing dynamic inventory setups. (coming soon)
- Setup and Deployment
- Running the Ansible Playbooks
- Lab Environment
- Troubleshooting
- Known Issues
- Contributing
- License
- About
- Additional Resources
The provided playbooks depend on specific Python versions and packages (see requirements.txt) and Ansible collections (see requirements.yml). If you have an existing Ansible setup, try your current environment first—it might work without modifications. Otherwise, follow the installation instructions below.
-
Clone the repository and set up the environment:
git clone https://github.com/narrowin-labs/ansible-mikrotik.git cd ansible-mikrotik python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ansible-galaxy collection install -r requirements.yml -p collections/
-
Deploy a test lab with containerlab:
clab deploy -t containerlabs/s3n.clab.yml
-
Run your first playbook:
ansible-playbook playbooks/mikrotik-configure.yml --limit mikrotik_s3n
- Ensure connectivity between your Ansible control node and the MikroTik devices for:
- SSH (Port: 22)
- API access (Port: 8728)
- SSL-API (Port: 8729)
[Ansible Playbook] --> [MikroTik RouterOS API:8728]
[Ansible Playbook] --> [MikroTik RouterOS SSL-API:8729]
[Ansible Playbook] --> [MikroTik RouterOS SSH:22] # some playbooks directly connect via ssh/scpWe provide some examples on how to use these playbooks to fully configure and backup MikroTik devices. The following sections describe the files that provide this magic.
All behavioral inventory parameters are defined in inventory/mikrotik. Check this file to identify the IPs for all switches and how to connect to them.
The group variables directory contains several important configuration files:
| File/Directory | Description |
|---|---|
| Adjust to your setup | |
| inventory/group_vars/mikrotik/ | Base configuration for all MikroTik devices |
| inventory/group_vars/all.yml | Global variables applied to all devices |
| No need to edit | |
| inventory/group_vars/mikrotik/ | RouterOS-specific settings for all MikroTik devices |
| inventory/group_vars/mikrotik_chr_12ports_containerlab/ | Settings specific to virtualized RouterOS instances with 12 ports |
| Only edit if you know what you are doing | |
| inventory/group_vars/mikrotik_switches/ | Configuration files specific to MikroTik switching hardware |
| inventory/group_vars/mikrotik_routers/ | WIP to come: Configuration files specific to MikroTik routing hardware |
Key configuration options include:
- mikrotik_user: Username for authentication.
- mikrotik_password: Password for authentication.
- local_backups_top_folder: Path to local backup folder on the ansible control host
- Additional Settings: Customize dns, ntp, snmp and other configurations according to your environment.
Ansible uses a variable precedence system where more specific variables override more general ones. The host variables (host_vars) directory contains configurations that are specific to individual devices and will override any matching variables defined in group variables (group_vars).
This creates a powerful inheritance model:
- Global settings defined in
group_vars/all.ymlapply to all devices - Group-specific settings like those in
group_vars/mikrotik/apply to all devices in that group - Host-specific settings in each device's folder under
host_vars/have the highest priority and override group settings
For example, if group_vars/mikrotik/interface.yml defines a standard interface configuration and host_vars/clab-s3n-sw-dist1/interface.yml defines specific settings for that device, the host-specific settings will take precedence for that particular device.
This allows you to:
- Define common configurations once at the group level
- Override only what's necessary for specific devices
- Maintain a clean, DRY (Don't Repeat Yourself) configuration structure
When troubleshooting, always check both host_vars and group_vars to understand the final applied configuration. Have a look at the Ansible debugging section
| File/Directory | Description |
|---|---|
| inventory/host_vars/clab-s3n-sw-dist1/ | Example configuration for a distribution switch |
| inventory/host_vars/clab-s3n-sw-acc1/ | Example configuration for an access switch |
| inventory/host_vars/clab-s3n-sw-acc2/ | Example configuration for a second access switch |
Here's a reference to all available playbooks:
| Playbook | Description |
|---|---|
| playbooks/mikrotik-backup-config.yml | Backs up RouterOS configuration files (.rsc files) |
| playbooks/mikrotik-backup-system.yml | Backs up RouterOS system (.backup files) |
| playbooks/mikrotik-configure.yml | Deploys full configuration to MikroTik devices |
| SSL-API | |
| playbooks/mikrotik-generate-ssl-certs.yml | Generates SSL certificates for API access |
| playbooks/mikrotik-configure-ssl-api.yml | Configures SSL API access on MikroTik devices |
| Operations | |
| playbooks/mikrotik-upgrade.yml | WIP: Upgrades RouterOS to specified version |
| playbooks/mikrotik-reset-config.yml | WIP: Factory resets device configuration |
| playbooks/mikrotik-reboot.yml | Safely reboots MikroTik devices |
| playbooks/mikrotik-check-versions.yml | Retrieves and displays current RouterOS versions |
| Facts gathering | |
| playbooks/mikrotik-resources-usage.yml | |
| More to come for routers and firewalls | ... |
- Network Device Access: Ensure connectivity between your Ansible control node and the MikroTik devices for SSH (Port: 22) and API-access (Port: 8728) or SSL-API (Port: 8729).
[Ansible Playbook] --> [MikroTik RouterOS API:8728]
[Ansible Playbook] --> [MikroTik RouterOS SSL-API:8729]
[Ansible Playbook] --> [MikroTik RouterOS SSH:22] # some playbooks directly connect via ssh/scpEvery device configuration option must be defined in the under inventory/group_vars or inventory/host_vars.
It's recommended to split the configuration variables in multiple files. The file name convention is to align the file name in the inventory with the api/cli endpoint to which the config is applied e.g.
file inventory/host_vars/clab-s3n-sw-dist1/interface_bridge.yml defines the configuration for api/cli endpoint /interface/bridge
Every variable must start with prefix routeros_ and then the api/cli endpoint where the config applies e.g. routeros_interface_bridge
In file [inventory/host_vars/clab-s3n-sw-dist1/interface_bridge.yml] you can find the variable named routeros_interface_bridge
- variable starting with prefix
routeros_indicates it's a variable defining a routeros configuration - variable ending with suffix
_interface_bridgeindicates it's a config option which applies to api/cli endpoint/interface/bridge
In production make sure you use ssl-api (disable cleartext), ansible-vault and if possible ssh key-based auth.
First generate the required SSL certs executing ansible-playbook playbooks/mikrotik-generate-ssl-certs.yml
Once you have the certs you can upload them to the devices and enable the API executing ansible-playbook playbooks/mikrotik-configure-ssl-api.yml
Use ssh-keys for authentication for login on the network devices.
-
private ssh key used for authentication should be located e.g. in
~/.ssh/id_rsa# configure in mikrotik group_vars -
Use ansible-vault to provide login- and API-credentials. This addition helps in daily operations to keep the credentials in a secure place.
-
ansible vault password should be stored in a text file in
playbook-network-switches/.vault.pass
ansible-playbook playbooks/mikrotik-backup-config.yml --limit mikrotik_s3nMikroTik config files will be stored in the ansible control host in backups/ unless reconfigured in inventory/group_vars/all.yml
ansible-playbook playbooks/mikrotik-backup-system.yml --limit mikrotik_s3nMikroTik system files will be stored in the ansible control host in backups/
Be aware that ansible-pylibssh won't work to transfer files from/to the mikrotik devices using ansible module ansible.netcommon.net_get.
You have to install the packages defined in requirements.txt inside your venv (paramiko + scp)
ansible-playbook playbooks/mikrotik-configure.yml --limit mikrotik_s3n --check --diffansible-playbook playbooks/mikrotik-configure.yml --limit mikrotik_s3nrun the playbook twice and see the wonders of idempotency (:
E.g.: bridge_ports in playbooks/mikrotik-configure.yml
ansible-playbook playbooks/mikrotik-configure.yml --limit mikrotik_s3n -t bridge_portsIf you want to test the playbooks using the labs we have prepared at: containerlabs you have two options:
- install containerlab on your machine. For this please follow: containerlab docs this guide
- use one of the provided docker envs described in Dockerized options. These contain a full installation of containerlab as well as the vs-code containerlab extension
The labs provided by this repo are:
- three MikroTik nodes interconnected and two Linux clients attached
Mikrotik CHRs:
User: admin Password: admin
Linux machines:
User: user Password: multit00l
clab deploy -t containerlabs/s3n.clab.ymlStart containerlab from the VS-Code extension
Navigate on the left to containerlab. Right click on the lab you want to start and choose Deploy
ssh admin@clab-s3n-sw-acct1Linux clients - User: user Password: multi00l
ssh user@clab-s3n-linux1 - Check all vars for resolved for a host
ansible -m debug -a "var=vars" clab-s3n-sw-acct1- Check the ansible groups for a device in the inventory
ansible -m debug -a var="hostvars[inventory_hostname]['group_names']" clab-s3n-sw-acct1Make sure the members of a bond don't belong to the bridge. This requires the right order in the playbook. You should first execute the task
-
configuring the bridge so the right interfaces are added/removed from/to the bridge
-
afterwards you can execute the task configuring the bond.
Every trunk port should have bpdu_guard: no in interface_bridge_ports.yml
TASK [Bond] **************************************************************************************************************************************************************************************************************************************************
fatal: [sw-mkt-03]: FAILED! => changed=false
msg: 'Error while creating entry for name="uplink-bond": failure: sfp-sfpplus3 already in bridge'
changed: [sw-mkt-02]This happens because the interfaces were manually added to the bridge during the initial setup. To fix it login to the switch and:
[user@sw-mkt-03] /interface/bridge/port> print
...
some output
...
56 H sfp-sfpplus1 bridge yes 1 0x80 10 10 none
;;; defconf
57 H sfp-sfpplus2 bridge yes 1 0x80 10 10 none
;;; defconf
58 IH sfp-sfpplus3 bridge yes 1 0x80 10 10 none
;;; defconf
59 IH sfp-sfpplus4 bridge yes 1 0x80 10 10 none
# delete the physical interfaces that are part of the new bond from the bridge
[user@sw-mkt-03] /interface/bridge/port> remove numbers=56,57,58,59
Contributions to ansible-mikrotik are welcome! Please follow these guidelines:
- Code Standards: Adhere to existing coding conventions and maintain clean, readable YAML and documentation.
- Issue Reporting: Open an issue if you find bugs or have feature requests.
- Pull Requests: Submit PRs with detailed descriptions of changes and reference any related issues.
- Documentation: Update this README and any inline documentation as necessary.
This project is licensed under the Apache License 2.0
The initial effort and development is a collaboration between narrowin.ch and scicore.ch. Our goal is to make network management easier and more reliable by providing robust, automated infrastructure as code for MikroTik environments.
Great videos by Roman Dodin:
- VS Code extension for Containerlab
- Containerlab and DevPod
- Running Containerlab on macOS and Windows with Devcontainers
Happy automating!