Name | Date | Size | #Lines | LOC | ||
---|---|---|---|---|---|---|
.. | 13-Oct-2021 | - | ||||
.github/workflows/ | H | 13-Oct-2021 | - | 311 | 267 | |
changelogs/ | H | 13-Oct-2021 | - | 114 | 110 | |
docs/docsite/ | H | 13-Oct-2021 | - | 282 | 211 | |
meta/ | H | 13-Oct-2021 | - | 3 | 2 | |
plugins/ | H | 13-Oct-2021 | - | 1,669 | 1,332 | |
tests/ | H | 13-Oct-2021 | - | 1,504 | 1,077 | |
CHANGELOG.rst | H A D | 29-Jun-2021 | 3 KiB | 97 | 60 | |
COPYING | H A D | 29-Jun-2021 | 34.3 KiB | 675 | 553 | |
FILES.json | H A D | 29-Jun-2021 | 15.8 KiB | 593 | 593 | |
MANIFEST.json | H A D | 29-Jun-2021 | 972 | 35 | 35 | |
README.md | H A D | 29-Jun-2021 | 5.6 KiB | 148 | 104 | |
codecov.yml | H A D | 29-Jun-2021 | 55 | 3 | 2 |
README.md
1# Community RouterOS Collection 2[![CI](https://github.com/ansible-collections/community.routeros/workflows/CI/badge.svg?event=push)](https://github.com/ansible-collections/community.routeros/actions) [![Codecov](https://img.shields.io/codecov/c/github/ansible-collections/community.routeros)](https://codecov.io/gh/ansible-collections/community.routeros) 3 4Provides modules for [Ansible](https://www.ansible.com/community) to manage [MikroTik RouterOS](http://www.mikrotik-routeros.net/routeros.aspx) instances. 5 6You can find [documentation for the modules and plugins in this collection here](https://ansible.fontein.de/collections/community/routeros/). 7 8## Tested with Ansible 9 10Tested with the current Ansible 2.9, ansible-base 2.10 and ansible-core 2.11 releases and the current development version of ansible-core. Ansible versions before 2.9.10 are not supported. 11 12## External requirements 13 14The exact requirements for every module are listed in the module documentation. 15 16### Supported connections 17 18The collection supports the `network_cli` connection. 19 20### Edge cases 21 22Please note that `community.routeros.api` module does **not** support Windows jump hosts! 23 24## Included content 25 26- `community.routeros.api` 27- `community.routeros.command` 28- `community.routeros.facts` 29 30You can find [documentation for the modules and plugins in this collection here](https://ansible.fontein.de/collections/community/routeros/). 31 32## Using this collection 33 34See [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for general detail on using collections. 35 36There are two approaches for using this collection. The `command` and `facts` modules use the `network_cli` connection and connect with SSH. The `api` module connects with the HTTP/HTTPS API. 37 38### Prerequisites 39 40The terminal-based modules in this collection (`community.routeros.command` and `community.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, the `community.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. 41 42```yaml 43- community.routeros.command: 44 commands: 45 - /ip 46 - print 47``` 48 49### Connecting with `network_cli` 50 51Example inventory `hosts` file: 52 53```.ini 54[routers] 55router ansible_host=192.168.1.1 56 57[routers:vars] 58ansible_connection=ansible.netcommon.network_cli 59ansible_network_os=community.routeros.routeros 60ansible_user=admin 61ansible_ssh_pass=test1234 62``` 63 64Example playbook: 65 66```.yaml 67--- 68- name: RouterOS test with network_cli connection 69 hosts: routers 70 gather_facts: false 71 tasks: 72 73 # Run a command and print its output 74 - community.routeros.command: 75 commands: 76 - /system resource print 77 register: system_resource_print 78 - debug: 79 var: system_resource_print.stdout_lines 80 81 # Retrieve facts 82 - community.routeros.facts: 83 - debug: 84 msg: "First IP address: {{ ansible_net_all_ipv4_addresses[0] }}" 85``` 86 87### Connecting with HTTP/HTTPS API 88 89Example playbook: 90 91```.yaml 92--- 93- name: RouterOS test with API 94 hosts: localhost 95 gather_facts: no 96 vars: 97 hostname: 192.168.1.1 98 username: admin 99 password: test1234 100 tasks: 101 - name: Get "ip address print" 102 community.routeros.api: 103 hostname: "{{ hostname }}" 104 password: "{{ password }}" 105 username: "{{ username }}" 106 path: "ip address" 107 tls: true 108 validate_certs: true 109 validate_cert_hostname: true 110 ca_path: /path/to/ca-certificate.pem 111 register: print_path 112``` 113 114## Contributing to this collection 115 116We're following the general Ansible contributor guidelines; see [Ansible Community Guide](https://docs.ansible.com/ansible/latest/community/index.html). 117 118If you want to clone this repositority (or a fork of it) to improve it, you can proceed as follows: 1191. Create a directory `ansible_collections/community`; 1202. In there, checkout this repository (or a fork) as `routeros`; 1213. Add the directory containing `ansible_collections` to your [ANSIBLE_COLLECTIONS_PATH](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#collections-paths). 122 123See [Ansible's dev guide](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html#contributing-to-collections) for more information. 124 125## Release notes 126 127See the [changelog](https://github.com/ansible-collections/community.routeros/blob/main/CHANGELOG.rst). 128 129## Roadmap 130 131We plan to regularly release minor and patch versions, whenever new features are added or bugs fixed. Our collection follows [semantic versioning](https://semver.org/), so breaking changes will only happen in major releases. 132 133## More information 134 135- [Ansible Collection overview](https://github.com/ansible-collections/overview) 136- [Ansible User guide](https://docs.ansible.com/ansible/latest/user_guide/index.html) 137- [Ansible Developer guide](https://docs.ansible.com/ansible/latest/dev_guide/index.html) 138- [Ansible Collections Checklist](https://github.com/ansible-collections/overview/blob/master/collection_requirements.rst) 139- [Ansible Community code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) 140- [The Bullhorn (the Ansible Contributor newsletter)](https://us19.campaign-archive.com/home/?u=56d874e027110e35dea0e03c1&id=d6635f5420) 141- [Changes impacting Contributors](https://github.com/ansible-collections/overview/issues/45) 142 143## Licensing 144 145GNU General Public License v3.0 or later. 146 147See [COPYING](https://www.gnu.org/licenses/gpl-3.0.txt) to see the full text. 148