Repository files navigation

Provides modules forAnsible to manageMikroTik RouterOS instances.

You can finddocumentation for the modules and plugins in this collection here.

We followAnsible Code of Conduct in all our interactions within this project.

If you encounter abusive behavior violating theAnsible Code of Conduct, please refer to thepolicy violations section of the Code of Conduct for information on how to raise a complaint.

• Join the Ansible forum:

  • Get Help: get help or help others.Please add appropriate tags if you start new discussions, for example therouteros tag.
  • Posts tagged with 'routeros': subscribe to participate in RouterOS related conversations.
  • Social Spaces: gather and interact with fellow enthusiasts.
  • News & Announcements: track project-wide announcements including social events.

• The AnsibleBullhorn newsletter: used to announce releases and important changes.

For more information about communication, see theAnsible communication guide.

Tested with the current ansible-core 2.15, ansible-core 2.16, ansible-core 2.17, ansible-core 2.18, and ansible-core 2.19 releases and the current development version of ansible-core. Ansible 2.9, ansible-base 2.10, and ansible-core versions before 2.15.0 are not supported.

The exact requirements for every module are listed in the module documentation.

The collection supports thenetwork_cli connection.

Please note thatcommunity.routeros.api module doesnot support Windows jump hosts!

Browsing thelatest collection documentation will show docs for thelatest version released in the Ansible package, not the latest version of the collection released on Galaxy.

Browsing thedevel collection documentation shows docs for thelatest version released on Galaxy.

We also separately publishlatest commit collection documentation which shows docs for thelatest commit in themain branch.

If you use the Ansible package and do not update collections independently, uselatest. If you install or update this collection directly from Galaxy, usedevel. If you are looking to contribute, uselatest commit.

• community.routeros.api
• community.routeros.api_facts
• community.routeros.api_find_and_modify
• community.routeros.api_info
• community.routeros.api_modify
• community.routeros.command
• community.routeros.facts

You can finddocumentation for the modules and plugins in this collection here.

SeeAnsible Using collections for general detail on using collections.

There are two approaches for using this collection. Thecommand andfacts modules use thenetwork_cli connection and connect with SSH. Theapi module connects with the HTTP/HTTPS API.

The terminal-based modules in this collection (community.routeros.command andcommunity.routeros.facts) do not support arbitrary symbols in router's identity. If you are having trouble connecting to your device, please make sure that your MikroTik's identity contains only alphanumeric characters and dashes. Also, thecommunity.routeros.command module does not support nesting commands and expects every command to start with a forward slash (/). Running the following command will produce an error.

-community.routeros.command:commands:      -/ip      -print

Example inventoryhosts file:

[routers]routeransible_host=192.168.1.1[routers:vars]ansible_connection=ansible.netcommon.network_cliansible_network_os=community.routeros.routerosansible_user=adminansible_ssh_pass=test1234

Example playbook:

---- name: RouterOS test with network_cli connectionhosts: routersgather_facts: falsetasks:- name: Run a commandcommunity.routeros.command:commands:- /system resource printregister: system_resource_print- name: Print its outputansible.builtin.debug:var: system_resource_print.stdout_lines- name: Retrieve factscommunity.routeros.facts:- ansible.builtin.debug:msg: "First IP address: {{ ansible_net_all_ipv4_addresses[0] }}"

Example playbook:

---- name: RouterOS test with APIhosts: localhostgather_facts: falsevars:hostname: 192.168.1.1username: adminpassword: test1234module_defaults:group/community.routeros.api:hostname: "{{ hostname }}"password: "{{ password }}"username: "{{ username }}"tls: trueforce_no_cert: falsevalidate_certs: truevalidate_cert_hostname: trueca_path: /path/to/ca-certificate.pemtasks:- name: Get "ip address print"community.routeros.api:path: ip addressregister: print_path- name: Print the resultansible.builtin.debug:var: print_path.msg- name: Change IP address to 192.168.1.1 for interface bridgecommunity.routeros.api_find_and_modify:path: ip addressfind:interface: bridgevalues:address: "192.168.1.1/24"- name: Retrieve factscommunity.routeros.api_facts:- ansible.builtin.debug:msg: "First IP address: {{ ansible_net_all_ipv4_addresses[0] }}"

We're following the general Ansible contributor guidelines; seeAnsible Community Guide.

If you want to clone this repositority (or a fork of it) to improve it, you can proceed as follows:

1. Create a directoryansible_collections/community;
2. In there, checkout this repository (or a fork) asrouteros;
3. Add the directory containingansible_collections to yourANSIBLE_COLLECTIONS_PATH.

SeeAnsible's dev guide for more information.

See thecollection's changelog.

We plan to regularly release minor and patch versions, whenever new features are added or bugs fixed. Our collection followssemantic versioning, so breaking changes will only happen in major releases.

• Ansible Collection overview
• Ansible User guide
• Ansible Developer guide
• Ansible Collections Checklist
• Ansible Community code of conduct
• The Bullhorn (the Ansible Contributor newsletter)
• Changes impacting Contributors

This collection is primarily licensed and distributed as a whole under the GNU General Public License v3.0 or later.

SeeLICENSES/GPL-3.0-or-later.txt for the full text.

Parts of the collection are licensed under theBSD 2-Clause license.

All files have a machine readableSDPX-License-Identifier: comment denoting its respective license(s) or an equivalent entry in an accompanying.license file. Only changelog fragments (which will not be part of a release) are covered by a blanket statement inREUSE.toml. This conforms to theREUSE specification.