{"id":24911266,"url":"https://github.com/narrowin/ansible-mikrotik","last_synced_at":"2025-10-03T20:32:57.401Z","repository":{"id":273665189,"uuid":"920417024","full_name":"narrowin/ansible-mikrotik","owner":"narrowin","description":"Ansible playbooks to fully manage and operate Mikrotik RouterOS networks","archived":false,"fork":false,"pushed_at":"2025-03-17T16:10:59.000Z","size":135,"stargazers_count":25,"open_issues_count":1,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-28T02:51:46.581Z","etag":null,"topics":["ansible","automation","mikrotik","network","open-source"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/narrowin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-22T05:33:07.000Z","updated_at":"2025-03-24T15:19:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"17e0307c-e71c-4c6f-84a7-950549e0edba","html_url":"https://github.com/narrowin/ansible-mikrotik","commit_stats":null,"previous_names":["narrowin/ansible-mikrotik"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narrowin%2Fansible-mikrotik","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narrowin%2Fansible-mikrotik/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narrowin%2Fansible-mikrotik/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narrowin%2Fansible-mikrotik/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/narrowin","download_url":"https://codeload.github.com/narrowin/ansible-mikrotik/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248890285,"owners_count":21178390,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","automation","mikrotik","network","open-source"],"created_at":"2025-02-02T04:19:01.893Z","updated_at":"2025-10-03T20:32:52.355Z","avatar_url":"https://github.com/narrowin.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# ansible-mikrotik\n\n[![Discord][discord-svg]][discord-url] [![DevPod][devpod-svg]][devpod-url] [![Codespaces][codespaces-svg]][codespaces-url]  \n![w212][w212][Learn more](https://containerlab.dev/macos/#devpod)![w90][w90][Learn more](https://containerlab.dev/manual/codespaces)\n\n[discord-svg]: https://github.com/user-attachments/assets/8f3f9813-fb61-4673-b666-5bb8dd902c05\n[discord-url]: https://discord.gg/6pbRj546gr\n[devpod-svg]: https://github.com/user-attachments/assets/6c09e524-850f-468d-b6d8-b2d65112b609\n[devpod-url]: https://devpod.sh/open#https://github.com/narrowin/ansible-mikrotik\n[codespaces-svg]: https://github.com/user-attachments/assets/95df8a45-cf92-4ce4-91dd-2142a04d28a3\n[codespaces-url]: https://codespaces.new/narrowin/ansible-mikrotik?quickstart=1\u0026devcontainer_path=.devcontainer%2Fdevcontainer.json\n[w212]: https://github.com/user-attachments/assets/7bd9ab55-dee2-436d-9a36-6cef335921e1\n[w90]: https://github.com/user-attachments/assets/f955fb52-9ae6-4b4d-9b06-63b8d44769d4\n\n## Automating MikroTik Device Management with Ansible\n\nansible-mikrotik enables network engineers to automate the configuration and management of [MikroTik](https://mikrotik.com) 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. \n\nIf you want to test this in a lab environment with virtualized MikroTik devices, you can use containerlab environment we have prepared.\n\n![mikrotik-ansible-workflow](https://github.com/user-attachments/assets/8479c7cd-35d2-4084-8848-c2895449d06f)\n\n\n## Example of a network configured with mikrotik-ansible\n\nCheck out the [narrowin demo controller](https://demo.narrowin.ch/) 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. \n\n![image](https://github.com/user-attachments/assets/48df496d-afaf-4586-9f40-48a362394852)\n\n\n---\n\n## Features\n\n- **Automated Configuration:** Quickly deploy and update MikroTik device settings including interfaces, routing, firewall rules, and VPN configurations.\n- **Idempotence:** Ensure configurations are applied consistently without unintended changes.\n- **Customizable Variables:** Easily override defaults to suit your configuration requirements.\n- **Modular Design:** Clean separation between tasks, defaults, and configuration files for easy maintenance and extension.\n- **Dynamic Inventory Support:** Integrate with your existing dynamic inventory setups. (coming soon)\n\n---\n\n## Table of Contents\n- [Setup and Deployment](#setup-and-deployment)\n- [Running the Ansible Playbooks](#running-and-testing-the-ansible-playbooks)\n- [Lab Environment](#lab-environment)\n- [Troubleshooting](#ansible-debugging)\n- [Known Issues](#caveats)\n- [Contributing](#contributing)\n- [License](#license)\n- [About](#about)\n- [Additional Resources](#additional-resources)\n\n---\n\n## Setup and Deployment\n\n### Ansible\n\nThe provided playbooks depend on specific Python versions and packages (see [requirements.txt](requirements.txt)) and Ansible collections (see [requirements.yml](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.\n\n### Quick Start Guide\n\n1. Clone the repository and set up the environment:\n   ```bash\n   git clone https://github.com/narrowin/ansible-mikrotik.git\n   cd ansible-mikrotik\n   python3 -m venv venv\n   source venv/bin/activate\n   pip install -r requirements.txt\n   ansible-galaxy collection install -r requirements.yml -p collections/\n   ```\n\n2. Deploy a test lab with containerlab:\n   ```bash\n   clab deploy -t containerlabs/s3n.clab.yml\n   ```\n\n3. Run your first playbook:\n   ```bash\n   ansible-playbook playbooks/mikrotik-configure.yml --limit mikrotik_s3n\n   ```\n\n### Network Requirements\n\n- Ensure connectivity between your Ansible control node and the MikroTik devices for:\n  - SSH (Port: 22)\n  - API access (Port: 8728)\n  - SSL-API (Port: 8729)\n\n```console\n[Ansible Playbook] --\u003e [MikroTik RouterOS API:8728]\n[Ansible Playbook] --\u003e [MikroTik RouterOS SSL-API:8729]\n[Ansible Playbook] --\u003e [MikroTik RouterOS SSH:22] # some playbooks directly connect via ssh/scp\n```\n\n### Ansible setup\n\nWe 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.\n\nAll [behavioral inventory parameters](https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html#connecting-to-hosts-behavioral-inventory-parameters) are defined in [inventory/mikrotik](inventory/mikrotik). \nCheck this file to identify the IPs for all switches and how to connect to them.\n\n#### Ansible Group Variables Structure\n\nThe group variables directory contains several important configuration files:\n\n| File/Directory | Description |\n|----------------|-------------|\n|Adjust to your setup||\n| [inventory/group_vars/mikrotik/](inventory/mikrotik/group_vars/mikrotik/) | Base configuration for all MikroTik devices |\n| [inventory/group_vars/all.yml](inventory/group_vars/all.yml) | Global variables applied to all devices |\n|No need to edit||\n| [inventory/group_vars/mikrotik/](inventory/group_vars/mikrotik/) | RouterOS-specific settings for all MikroTik devices |\n| [inventory/group_vars/mikrotik_chr_12ports_containerlab/](inventory/group_vars/mikrotik_chr_12ports_containerlab/) | Settings specific to virtualized RouterOS instances with 12 ports |\n|Only edit if you know what you are doing||\n| [inventory/group_vars/mikrotik_switches/](inventory/group_vars/mikrotik_switches/) | Configuration files specific to MikroTik switching hardware |\n| [inventory/group_vars/mikrotik_routers/](inventory/group_vars/mikrotik_routers/) | WIP to come: Configuration files specific to MikroTik routing hardware |\n\n\n##### Global group_vars for all devices \n[Key configuration options](inventory/group_vars/all.yml) include:\n\n- **mikrotik_user:** Username for authentication.\n- **mikrotik_password:** Password for authentication.\n- **local_backups_top_folder:** Path to local backup folder on the ansible control host\n- **Additional Settings:** Customize dns, ntp, snmp and other configurations according to your environment.\n\n\n#### Ansible Host Variables Structure\n\nAnsible 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`).\n\nThis creates a powerful inheritance model:\n\n1. **Global settings** defined in `group_vars/all.yml` apply to all devices\n2. **Group-specific settings** like those in `group_vars/mikrotik/` apply to all devices in that group\n3. **Host-specific settings** in each device's folder under `host_vars/` have the highest priority and override group settings\n\nFor 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.\n\nThis allows you to:\n- Define common configurations once at the group level\n- Override only what's necessary for specific devices\n- Maintain a clean, DRY (Don't Repeat Yourself) configuration structure\n\nWhen troubleshooting, always check both host_vars and group_vars to understand the final applied configuration. Have a look at the [Ansible debugging section](#ansible-debugging)\n\n| File/Directory | Description |\n|----------------|-------------|\n| [inventory/host_vars/clab-s3n-sw-dist1/](inventory/host_vars/clab-s3n-sw-dist1/) | Example configuration for a distribution switch |\n| [inventory/host_vars/clab-s3n-sw-acc1/](inventory/host_vars/clab-s3n-sw-acc1/) | Example configuration for an access switch |\n| [inventory/host_vars/clab-s3n-sw-acc2/](inventory/host_vars/clab-s3n-sw-acc2/) | Example configuration for a second access switch |\n\n#### Playbooks\n\nHere's a reference to all available playbooks:\n\n| Playbook | Description |\n|----------|-------------|\n| [playbooks/mikrotik-backup-config.yml](playbooks/mikrotik-backup-config.yml) | Backs up RouterOS configuration files (.rsc files)|\n| [playbooks/mikrotik-backup-system.yml](playbooks/mikrotik-backup-system.yml) | Backs up RouterOS system (.backup files)|\n| [playbooks/mikrotik-configure.yml](playbooks/mikrotik-configure.yml) | Deploys full configuration to MikroTik devices |\n|SSL-API||\n| [playbooks/mikrotik-generate-ssl-certs.yml](playbooks/mikrotik-generate-ssl-certs.yml) | Generates SSL certificates for API access |\n| [playbooks/mikrotik-configure-ssl-api.yml](playbooks/mikrotik-configure-ssl-api.yml) | Configures SSL API access on MikroTik devices |\n|Operations||\n| [playbooks/mikrotik-upgrade.yml](playbooks/mikrotik-upgrade.yml) | WIP: Upgrades RouterOS to specified version |\n| [playbooks/mikrotik-reset-config.yml](playbooks/mikrotik-reset-config.yml) | WIP: Factory resets device configuration |\n| [playbooks/mikrotik-reboot.yml](playbooks/mikrotik-reboot.yml) | Safely reboots MikroTik devices |\n| [playbooks/mikrotik-check-versions.yml](playbooks/mikrotik-check-versions.yml) | Retrieves and displays current RouterOS versions |\n|Facts gathering||\n| [playbooks/mikrotik-resources-usage.yml](playbooks/mikrotik-resources-usage.yml) | |\n|More to come for routers and firewalls|...|\n\n\n##### Network Requirements for the playbooks\n\n- **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).\n\n```console\n[Ansible Playbook] --\u003e [MikroTik RouterOS API:8728]\n[Ansible Playbook] --\u003e [MikroTik RouterOS SSL-API:8729]\n[Ansible Playbook] --\u003e [MikroTik RouterOS SSH:22] # some playbooks directly connect via ssh/scp\n```\n\n#### Naming convention for inventory files and variables\n\nEvery device configuration option must be defined in the under [inventory/group_vars](inventory/group_vars) or [inventory/host_vars](inventory/host_vars).\n\n##### Naming convention for inventory file names\n\nIt'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.\n\nfile [inventory/host_vars/clab-s3n-sw-dist1/interface_bridge.yml](inventory/host_vars/clab-s3n-sw-dist1/interface_bridge.yml) defines the configuration for api/cli endpoint `/interface/bridge`\n\n##### Naming convention for inventory var names\n\nEvery variable must start with prefix `routeros_` and then the api/cli endpoint where the config applies e.g. `routeros_interface_bridge`\n\nIn file [inventory/host_vars/clab-s3n-sw-dist1/interface_bridge.yml] you can find the variable named `routeros_interface_bridge`\n\n  * variable starting with prefix `routeros_` indicates it's a variable defining a routeros configuration\n  * variable ending with suffix `_interface_bridge` indicates it's a config option which applies to api/cli endpoint `/interface/bridge`\n\n\n## For production usage\n\nIn production make sure you use ssl-api (disable cleartext), ansible-vault and if possible ssh key-based auth. \n\n### How to enable API with SSL in mikrotik devices\n\nFirst generate the required SSL certs executing `ansible-playbook playbooks/mikrotik-generate-ssl-certs.yml`\n\nOnce you have the certs you can upload them to the devices and enable the API executing `ansible-playbook playbooks/mikrotik-configure-ssl-api.yml`\n\n### Authentication with ssh-key and ansible-vault\n\nUse ssh-keys for authentication for login on the network devices.\n\n- private ssh key used for authentication should be located e.g. in `~/.ssh/id_rsa` # configure in mikrotik group_vars\n\n- Use ansible-vault to provide login- and API-credentials. This addition helps in daily operations to keep the credentials in a secure place.\n\n- ansible vault password should be stored in a text file in `playbook-network-switches/.vault.pass`\n\n\n---\n\n## Running and testing the ansible playbooks\n\n### Backup config of mikrotik switches\n\n```bash\nansible-playbook playbooks/mikrotik-backup-config.yml --limit mikrotik_s3n\n```\n\nMikroTik config files will be stored in the ansible control host in `backups/` unless reconfigured in [inventory/group_vars/all.yml](inventory/group_vars/all.yml)\n\n### Backup system files mikrotik switches\n\n```bash\nansible-playbook playbooks/mikrotik-backup-system.yml --limit mikrotik_s3n\n```\n\nMikroTik system files will be stored in the ansible control host in `backups/`\n\n### mikrotik file transfers\n\nBe aware that ansible-pylibssh won't work to transfer files from/to the mikrotik devices using ansible module `ansible.netcommon.net_get`.\nYou have to install the packages defined in `requirements.txt` inside your venv (paramiko + scp)\n\n### Full device configuration\n\n#### Ansible dry run and show diff\n\n```bash\nansible-playbook playbooks/mikrotik-configure.yml --limit mikrotik_s3n --check --diff\n```\n\n#### Push config\n\n```bash\nansible-playbook playbooks/mikrotik-configure.yml --limit mikrotik_s3n\n```\n\nrun the playbook twice and see the wonders of idempotency (:\n\n#### Push only specific parts/tags\n\nE.g.: bridge_ports in [playbooks/mikrotik-configure.yml](playbooks/mikrotik-configure.yml)\n\n```bash\nansible-playbook playbooks/mikrotik-configure.yml --limit mikrotik_s3n -t bridge_ports\n```\n\n---\n\n## Lab Environment\n\nIf you want to test the playbooks using the labs we have prepared at: [containerlabs](containerlabs/) you have two options:\n\n- install containerlab on your machine. For this please follow: [containerlab docs](https://containerlab.dev/quickstart/) this guide\n- use one of the provided docker envs described in [Dockerized options](#dockerized-options). These contain a full installation of containerlab as well as the vs-code containerlab extension\n\n### Quick start options with containerlab\n\nThe labs provided by this repo are:\n\n- [three MikroTik nodes](containerlabs/s3n.clab.yml) interconnected and two Linux clients attached\n\n### Lab Credentials\n\n```\nMikrotik CHRs: \n  User: admin Password: admin\nLinux machines: \n  User: user Password: multit00l\n```\n\n#### Start containerlab from the terminal\n```bash\nclab deploy -t containerlabs/s3n.clab.yml\n```\n\n#### Start containerlab from the [VS-Code extension](https://containerlab.dev/manual/vsc-extension/)\n\nNavigate on the left to containerlab. Right click on the lab you want to start and choose `Deploy`\n\n\n## Login to Lab devices\n\n\n```bash\nssh admin@clab-s3n-sw-acct1\n```\n\nLinux clients - User: user Password: multi00l\n\n```bash\nssh user@clab-s3n-linux1 \n```\n\n---\n\n## Ansible Debugging\n\n- Check all vars for resolved for a host\n```bash\nansible -m debug -a \"var=vars\" clab-s3n-sw-acct1\n```\n\n- Check the ansible groups for a device in the inventory\n\n```bash\nansible -m debug -a var=\"hostvars[inventory_hostname]['group_names']\" clab-s3n-sw-acct1\n```\n\n---\n\n## Caveats\n\n### Details about bonding\n\nMake 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\n\n- configuring the bridge so the right interfaces are added/removed from/to the bridge\n\n- **afterwards** you can execute the task configuring the bond.\n\n### Details about trunk ports\n\nEvery trunk port should have `bpdu_guard: no` in `interface_bridge_ports.yml`\n\n### common error\n\n```console\nTASK [Bond] **************************************************************************************************************************************************************************************************************************************************\nfatal: [sw-mkt-03]: FAILED! =\u003e changed=false\n  msg: 'Error while creating entry for name=\"uplink-bond\": failure: sfp-sfpplus3 already in bridge'\n  changed: [sw-mkt-02]\n```\n\nThis happens because the interfaces were manually added to the bridge during the initial setup. To fix it login to the switch and:\n\n```console\n[user@sw-mkt-03] /interface/bridge/port\u003e print     \n...\nsome output \n...\n56  H sfp-sfpplus1  bridge  yes     1  0x80             10                  10  none   \n;;; defconf\n57  H sfp-sfpplus2  bridge  yes     1  0x80             10                  10  none   \n;;; defconf\n58 IH sfp-sfpplus3  bridge  yes     1  0x80             10                  10  none   \n;;; defconf\n59 IH sfp-sfpplus4  bridge  yes     1  0x80             10                  10  none   \n\n# delete the physical interfaces that are part of the new bond from the bridge\n[user@sw-mkt-03] /interface/bridge/port\u003e remove numbers=56,57,58,59\n\n```\n\n## Contributing\n\nContributions to ansible-mikrotik are welcome! Please follow these guidelines:\n\n- **Code Standards:** Adhere to existing coding conventions and maintain clean, readable YAML and documentation.\n- **Issue Reporting:** Open an issue if you find bugs or have feature requests.\n- **Pull Requests:** Submit PRs with detailed descriptions of changes and reference any related issues.\n- **Documentation:** Update this README and any inline documentation as necessary.\n\n---\n\n## License\n\nThis project is licensed under the [Apache License 2.0](LICENSE)\n\n---\n\n## About\n\nThe initial effort and development is a collaboration between [narrowin.ch](https://narrowin.ch) and [scicore.ch](https://scicore.ch). Our goal is to make network management easier and more reliable by providing robust, automated infrastructure as code for MikroTik environments.\n\n---\n\n## Additional Resources\n\n- [Ansible Documentation](https://docs.ansible.com/)\n- [Ansible RouterOS collection](https://docs.ansible.com/ansible/latest/collections/community/routeros/index.html)\n- [Mikrotik RouterOS Documentation](https://help.mikrotik.com/docs/)\n- [Containerlab](https://containerlab.dev/)\n\n### Containerlab, devpod, codespaces and VS-code extension\n\nGreat videos by [Roman Dodin](https://github.com/hellt):\n\n\n- [VS Code extension for Containerlab](https://www.youtube.com/watch?v=NIw1PbfCyQ4)\n- [Containerlab and DevPod](https://www.youtube.com/watch?v=ceDrFx2K3jE)\n- [Running Containerlab on macOS and Windows with Devcontainers](https://www.youtube.com/watch?v=Xue1pLiO0qQ)\n\n---\n\n*Happy automating!*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnarrowin%2Fansible-mikrotik","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnarrowin%2Fansible-mikrotik","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnarrowin%2Fansible-mikrotik/lists"}