diff --git a/README.md b/README.md index f501c15..b1d52a9 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,8 @@ Please note that `community.routeros.api` module does **not** support Windows ju ## Included content - `community.routeros.api` +- `community.routeros.api_facts` +- `community.routeros.api_find_and_modify` - `community.routeros.command` - `community.routeros.facts` @@ -69,19 +71,19 @@ Example playbook: hosts: routers gather_facts: false tasks: + - name: Run a command + community.routeros.command: + commands: + - /system resource print + register: system_resource_print + - name: Print its output + ansible.builtin.debug: + var: system_resource_print.stdout_lines - # Run a command and print its output - - community.routeros.command: - commands: - - /system resource print - register: system_resource_print - - debug: - var: system_resource_print.stdout_lines - - # Retrieve facts - - community.routeros.facts: - - debug: - msg: "First IP address: {{ ansible_net_all_ipv4_addresses[0] }}" + - name: Retrieve facts + community.routeros.facts: + - ansible.builtin.debug: + msg: "First IP address: {{ ansible_net_all_ipv4_addresses[0] }}" ``` ### Connecting with HTTP/HTTPS API @@ -97,18 +99,36 @@ Example playbook: hostname: 192.168.1.1 username: admin password: test1234 + module_defaults: + group/community.routeros.api: + hostname: "{{ hostname }}" + password: "{{ password }}" + username: "{{ username }}" + tls: true + validate_certs: true + validate_cert_hostname: true + ca_path: /path/to/ca-certificate.pem tasks: - name: Get "ip address print" community.routeros.api: - hostname: "{{ hostname }}" - password: "{{ password }}" - username: "{{ username }}" - path: "ip address" - tls: true - validate_certs: true - validate_cert_hostname: true - ca_path: /path/to/ca-certificate.pem + path: ip address register: print_path + - name: Print the result + ansible.builtin.debug: + var: print_path.msg + + - name: Change IP address to 192.168.1.1 for interface bridge + community.routeros.api_find_and_modify: + path: ip address + find: + interface: bridge + values: + address: "192.168.1.1/24" + + - name: Retrieve facts + community.routeros.api_facts: + - ansible.builtin.debug: + msg: "First IP address: {{ ansible_net_all_ipv4_addresses[0] }}" ``` ## Contributing to this collection diff --git a/docs/docsite/rst/api-guide.rst b/docs/docsite/rst/api-guide.rst index bccdcfe..a8a9e9a 100644 --- a/docs/docsite/rst/api-guide.rst +++ b/docs/docsite/rst/api-guide.rst @@ -3,7 +3,7 @@ How to connect to RouterOS devices with the RouterOS API ======================================================== -You can use the :ref:`community.routeros.api module ` to connect to a RouterOS device with the RouterOS API. The :ref:`community.routeros.api_facts module ` allows to retrieve Ansible facts using the RouterOS API. +You can use the :ref:`community.routeros.api module ` to connect to a RouterOS device with the RouterOS API. A more specific module to modify certain entries is the :ref:`community.routeros.api_find_and_modify module `. The :ref:`community.routeros.api_facts module ` allows to retrieve Ansible facts using the RouterOS API. No special setup is needed; the module needs to be run on a host that can connect to the device's API. The most common case is that the module is run on ``localhost``, either by using ``hosts: localhost`` in the playbook, or by using ``delegate_to: localhost`` for the task. The following example shows how to run the equivalent of ``/ip address print``: @@ -59,7 +59,7 @@ Check out the documenation of the :ref:`community.routeros.api module ` and :ref:`community.routeros.api_facts module ` in every task, you can use the ``community.routeros.api`` module defaults group: +To avoid having to specify common parameters for all the API based modules in every task, you can use the ``community.routeros.api`` module defaults group: .. code-block:: yaml+jinja @@ -87,7 +87,15 @@ To avoid having to specify common parameters for the :ref:`community.routeros.ap community.routeros.api: path: "ip address" -Here both tasks will use the options set for the module defaults group. + - name: Change IP address to 192.168.1.1 for interface bridge + community.routeros.api_find_and_modify: + path: ip address + find: + interface: bridge + values: + address: "192.168.1.1/24" + +Here all three tasks will use the options set for the module defaults group. Setting up encryption ---------------------