diff options
Diffstat (limited to 'ansible_collections/community/routeros/docs')
3 files changed, 27 insertions, 25 deletions
diff --git a/ansible_collections/community/routeros/docs/docsite/rst/api-guide.rst b/ansible_collections/community/routeros/docs/docsite/rst/api-guide.rst index f3bb6295b..6140d819d 100644 --- a/ansible_collections/community/routeros/docs/docsite/rst/api-guide.rst +++ b/ansible_collections/community/routeros/docs/docsite/rst/api-guide.rst @@ -8,7 +8,7 @@ How to connect to RouterOS devices with the RouterOS API ======================================================== -You can use the :ref:`community.routeros.api module <ansible_collections.community.routeros.api_module>` to connect to a RouterOS device with the RouterOS API. More specific module to modify certain entries are the :ref:`community.routeros.api_modify <ansible_collections.community.routeros.api_modify_module>` and :ref:`community.routeros.api_find_and_modify <ansible_collections.community.routeros.api_find_and_modify_module>` modules. The :ref:`community.routeros.api_info module <ansible_collections.community.routeros.api_info_module>` allows to retrieve information on specific predefined paths that can be used as input for the ``community.routeros.api_modify`` module, and the :ref:`community.routeros.api_facts module <ansible_collections.community.routeros.api_facts_module>` allows to retrieve Ansible facts using the RouterOS API. +You can use the :ansplugin:`community.routeros.api module <community.routeros.api#module>` to connect to a RouterOS device with the RouterOS API. More specific module to modify certain entries are the :ansplugin:`community.routeros.api_modify <community.routeros.api_modify#module>` and :ansplugin:`community.routeros.api_find_and_modify <community.routeros.api_find_and_modify#module>` modules. The :ansplugin:`community.routeros.api_info module <community.routeros.api_info#module>` allows to retrieve information on specific predefined paths that can be used as input for the :ansplugin:`community.routeros.api_modify <community.routeros.api_modify#module>` module, and the :ansplugin:`community.routeros.api_facts module <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,12 +59,12 @@ This results in the following output: PLAY RECAP ******************************************************************************************************* localhost : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -Check out the documenation of the :ref:`community.routeros.api module <ansible_collections.community.routeros.api_module>` for details on the options. +Check out the documentation of the :ansplugin:`community.routeros.api module <community.routeros.api#module>` for details on the options. Using 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: +To avoid having to specify common parameters for all the API based modules in every task, you can use the ``community.routeros.api`` :ref:`module defaults group <module_defaults_groups>`: .. code-block:: yaml+jinja @@ -73,7 +73,7 @@ To avoid having to specify common parameters for all the API based modules in ev hosts: localhost gather_facts: false module_defaults: - group/community.routeros.api + group/community.routeros.api: hostname: 192.168.1.1 password: admin username: test1234 @@ -85,7 +85,7 @@ To avoid having to specify common parameters for all the API based modules in ev # If you are using your own PKI, specify the path to your CA certificate here: # ca_path: /path/to/ca-certificate.pem tasks: - - name: Gather facts" + - name: Gather facts community.routeros.api_facts: - name: Get "ip address print" @@ -105,12 +105,12 @@ Here all three tasks will use the options set for the module defaults group. Setting up encryption --------------------- -It is recommended to always use ``tls: true`` when connecting with the API, even if you are only connecting to the device through a trusted network. The following options control how TLS/SSL is used: +It is recommended to always use :ansopt:`tls=true` when connecting with the API, even if you are only connecting to the device through a trusted network. The following options control how TLS/SSL is used: -:force_no_cert: Setting to ``true`` connects to the device without a certificate. **This is discouraged to use in production and is susceptible to Man-in-the-Middle attacks**, but might be useful when setting the device up. The default value is ``false``. -:validate_certs: Setting to ``false`` disables any certificate validation. **This is discouraged to use in production**, but is needed when setting the device up. The default value is ``true``. -:validate_cert_hostname: Setting to ``false`` (default) disables hostname verification during certificate validation. This is needed if the hostnames specified in the certificate do not match the hostname used for connecting (usually the device's IP). It is recommended to set up the certificate correctly and set this to ``true``; the default ``false`` is chosen for backwards compatibility to an older version of the module. -:ca_path: If you are not using a commerically trusted CA certificate to sign your device's certificate, or have not included your CA certificate in Python's truststore, you need to point this option to the CA certificate. +:force_no_cert: Setting to :ansval:`true` connects to the device without a certificate. **This is discouraged to use in production and is susceptible to Man-in-the-Middle attacks**, but might be useful when setting the device up. The default value is :ansval:`false`. +:validate_certs: Setting to :ansval:`false` disables any certificate validation. **This is discouraged to use in production**, but is needed when setting the device up. The default value is :ansval:`true`. +:validate_cert_hostname: Setting to :ansval:`false` (default) disables hostname verification during certificate validation. This is needed if the hostnames specified in the certificate do not match the hostname used for connecting (usually the device's IP). It is recommended to set up the certificate correctly and set this to :ansval:`true`; the default :ansval:`false` is chosen for backwards compatibility to an older version of the module. +:ca_path: If you are not using a commercially trusted CA certificate to sign your device's certificate, or have not included your CA certificate in Python's truststore, you need to point this option to the CA certificate. We recommend to create a CA certificate that is used to sign the certificates for your RouterOS devices, and have the certificates include the correct hostname(s), including the IP of the device. That way, you can fully enable TLS and be sure that you always talk to the correct device. @@ -124,7 +124,7 @@ Installing a certificate on a MikroTik router Installing the certificate is best done with the SSH connection. (See the :ref:`ansible_collections.community.routeros.docsite.ssh-guide` guide for more information.) Once the certificate has been installed, and the HTTPS API enabled, it's easier to work with the API, since it has a quite a few less problems, and returns data as JSON objects instead of text you first have to parse. -First you have to convert the certificate and its private key to a `PKCS #12 bundle <https://en.wikipedia.org/wiki/PKCS_12>`_. This can be done with the :ref:`community.crypto.openssl_pkcs12 <ansible_collections.community.crypto.openssl_pkcs12_module>`. The following playbook assumes that the certificate is available as ``keys/{{ inventory_hostname }}.pem``, and its private key is available as ``keys/{{ inventory_hostname }}.key``. It generates a random passphrase to protect the PKCS#12 file. +First you have to convert the certificate and its private key to a `PKCS #12 bundle <https://en.wikipedia.org/wiki/PKCS_12>`_. This can be done with the :ansplugin:`community.crypto.openssl_pkcs12 <community.crypto.openssl_pkcs12#module>`. The following playbook assumes that the certificate is available as ``keys/{{ inventory_hostname }}.pem``, and its private key is available as ``keys/{{ inventory_hostname }}.key``. It generates a random passphrase to protect the PKCS#12 file. .. code-block:: yaml+jinja @@ -186,7 +186,7 @@ First you have to convert the certificate and its private key to a `PKCS #12 bun The playbook also assumes that ``admin_network`` describes the network from which the HTTPS and API interface can be accessed. This can be for example ``192.168.1.0/24``. -When this playbook completed successfully, you should be able to use the HTTPS admin interface (reachable in a browser from ``https://192.168.1.1/``, with the correct IP inserted), as well as the :ref:`community.routeros.api module <ansible_collections.community.routeros.api_module>` module with TLS and certificate validation enabled: +When this playbook completed successfully, you should be able to use the HTTPS admin interface (reachable in a browser from ``https://192.168.1.1/``, with the correct IP inserted), as well as the :ansplugin:`community.routeros.api module <community.routeros.api#module>` module with TLS and certificate validation enabled: .. code-block:: yaml+jinja diff --git a/ansible_collections/community/routeros/docs/docsite/rst/quoting.rst b/ansible_collections/community/routeros/docs/docsite/rst/quoting.rst index 3091fc857..b1c045382 100644 --- a/ansible_collections/community/routeros/docs/docsite/rst/quoting.rst +++ b/ansible_collections/community/routeros/docs/docsite/rst/quoting.rst @@ -8,12 +8,12 @@ How to quote and unquote commands and arguments =============================================== -When using the :ref:`community.routeros.command module <ansible_collections.community.routeros.command_module>` or the :ref:`community.routeros.api module <ansible_collections.community.routeros.api_module>` modules, you need to pass text data in quoted form. While in some cases quoting is not needed (when passing IP addresses or names without spaces, for example), in other cases it is required, like when passing a comment which contains a space. +When using the :ansplugin:`community.routeros.command module <community.routeros.command#module>` or the :ansplugin:`community.routeros.api module <community.routeros.api#module>` modules, you need to pass text data in quoted form. While in some cases quoting is not needed (when passing IP addresses or names without spaces, for example), in other cases it is required, like when passing a comment which contains a space. The community.routeros collection provides a set of Jinja2 filter plugins which helps you with these tasks: -- The :ref:`community.routeros.quote_argument_value filter <ansible_collections.community.routeros.quote_argument_value_filter>` quotes an argument value: ``'this is a "comment"' | community.routeros.quote_argument_value == '"this is a \\"comment\\""'``. -- The :ref:`community.routeros.quote_argument filter <ansible_collections.community.routeros.quote_argument_filter>` quotes an argument with or without a value: ``'comment=this is a "comment"' | community.routeros.quote_argument == 'comment="this is a \\"comment\\""'``. -- The :ref:`community.routeros.join filter <ansible_collections.community.routeros.join_filter>` quotes a list of arguments and joins them to one string: ``['foo=bar', 'comment=foo is bar'] | community.routeros.join == 'foo=bar comment="foo is bar"'``. -- The :ref:`community.routeros.split filter <ansible_collections.community.routeros.split_filter>` splits a command into a list of arguments (with or without values): ``'foo=bar comment="foo is bar"' | community.routeros.split == ['foo=bar', 'comment=foo is bar']`` -- The :ref:`community.routeros.list_to_dict filter <ansible_collections.community.routeros.list_to_dict_filter>` splits a list of arguments with values into a dictionary: ``['foo=bar', 'comment=foo is bar'] | community.routeros.list_to_dict == {'foo': 'bar', 'comment': 'foo is bar'}``. It has two optional arguments: ``require_assignment`` (default value ``true``) allows to accept arguments without values when set to ``false``; and ``skip_empty_values`` (default value ``false``) allows to skip arguments whose value is empty. +- The :ansplugin:`community.routeros.quote_argument_value filter <community.routeros.quote_argument_value#filter>` quotes an argument value: ``'this is a "comment"' | community.routeros.quote_argument_value == '"this is a \\"comment\\""'``. +- The :ansplugin:`community.routeros.quote_argument filter <community.routeros.quote_argument#filter>` quotes an argument with or without a value: ``'comment=this is a "comment"' | community.routeros.quote_argument == 'comment="this is a \\"comment\\""'``. +- The :ansplugin:`community.routeros.join filter <community.routeros.join#filter>` quotes a list of arguments and joins them to one string: ``['foo=bar', 'comment=foo is bar'] | community.routeros.join == 'foo=bar comment="foo is bar"'``. +- The :ansplugin:`community.routeros.split filter <community.routeros.split#filter>` splits a command into a list of arguments (with or without values): ``'foo=bar comment="foo is bar"' | community.routeros.split == ['foo=bar', 'comment=foo is bar']`` +- The :ansplugin:`community.routeros.list_to_dict filter <community.routeros.list_to_dict#filter>` splits a list of arguments with values into a dictionary: ``['foo=bar', 'comment=foo is bar'] | community.routeros.list_to_dict == {'foo': 'bar', 'comment': 'foo is bar'}``. It has two optional arguments: :ansopt:`community.routeros.list_to_dict#filter:require_assignment` (default value :ansval:`true`) allows to accept arguments without values when set to :ansval:`false`; and :ansopt:`community.routeros.list_to_dict#filter:skip_empty_values` (default value :ansval:`false`) allows to skip arguments whose value is empty. diff --git a/ansible_collections/community/routeros/docs/docsite/rst/ssh-guide.rst b/ansible_collections/community/routeros/docs/docsite/rst/ssh-guide.rst index bdbdbfe84..4b0eb2017 100644 --- a/ansible_collections/community/routeros/docs/docsite/rst/ssh-guide.rst +++ b/ansible_collections/community/routeros/docs/docsite/rst/ssh-guide.rst @@ -10,17 +10,17 @@ How to connect to RouterOS devices with SSH The collection offers two modules to connect to RouterOS devies with SSH: -- The :ref:`community.routeros.facts module <ansible_collections.community.routeros.facts_module>` gathers facts about a RouterOS device; -- The :ref:`community.routeros.command module <ansible_collections.community.routeros.command_module>` executes commands on a RouterOS device. +- The :ansplugin:`community.routeros.facts module <community.routeros.facts#module>` gathers facts about a RouterOS device; +- The :ansplugin:`community.routeros.command module <community.routeros.command#module>` executes commands on a RouterOS device. -The modules need the :ref:`ansible.netcommon.network_cli connection plugin <ansible_collections.ansible.netcommon.network_cli_connection>` for this. +The modules need the :ansplugin:`ansible.netcommon.network_cli connection plugin <ansible.netcommon.network_cli#connection>` for this. Important notes --------------- 1. The SSH-based modules do not support arbitrary symbols in the 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 make sure that the identity string is not longer than 19 characters (`see issue for details <https://github.com/ansible-collections/community.routeros/issues/31>`__). Similar problems can happen for unsupported characters in your username. -2. The :ref:`community.routeros.command module <ansible_collections.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: +2. The :ansplugin:`community.routeros.command module <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: .. code-block:: yaml+jinja @@ -29,9 +29,11 @@ Important notes - /ip - print -3. When using the :ref:`community.routeros.command module <ansible_collections.community.routeros.command_module>` module, make sure to not specify too long commands. Alternatively, add something like ``+cet512w`` to the username (replace ``admin`` with ``admin+cet512w``) to tell RouterOS to not wrap before 512 characters in a line (`see issue for details <https://github.com/ansible-collections/community.routeros/issues/6>`__). +3. When using the :ansplugin:`community.routeros.command module <community.routeros.command#module>` module, make sure to not specify too long commands. Alternatively, add something like ``+cet512w`` to the username (replace ``admin`` with ``admin+cet512w``) to tell RouterOS to not wrap before 512 characters in a line (`see issue for details <https://github.com/ansible-collections/community.routeros/issues/6>`__). -4. Finally, the :ref:`ansible.netcommon.network_cli connection plugin <ansible_collections.ansible.netcommon.network_cli_connection>` uses `paramiko <https://pypi.org/project/paramiko/>`_ by default to connect to devices with SSH. You can set its ``ssh_type`` option to ``libssh`` to use `ansible-pylibssh <https://pypi.org/project/ansible-pylibssh/>`_ instead, which offers Python bindings to libssh. See its documentation for details. +4. The :ansplugin:`ansible.netcommon.network_cli connection plugin <ansible.netcommon.network_cli#connection>` uses `paramiko <https://pypi.org/project/paramiko/>`_ by default to connect to devices with SSH. You can set its :ansopt:`ansible.netcommon.network_cli#connection:ssh_type` option to :ansval:`libssh` to use `ansible-pylibssh <https://pypi.org/project/ansible-pylibssh/>`_ instead, which offers Python bindings to libssh. See its documentation for details. + +5. User is **not allowed** to login via SSH by password to modern Mikrotik if SSH key for the user is added! Setting up an inventory ----------------------- @@ -49,7 +51,7 @@ An example inventory ``hosts`` file for a RouterOS device is as follows: ansible_user=admin ansible_ssh_pass=test1234 -This tells Ansible that you have a RouterOS device called ``router`` with IP ``192.168.2.1``. Ansible should use the :ref:`ansible.netcommon.network_cli connection plugin <ansible_collections.ansible.netcommon.network_cli_connection>` together with the the :ref:`community.routeros.routeros cliconf plugin <ansible_collections.community.routeros.routeros_cliconf>`. The credentials are stored as ``ansible_user`` and ``ansible_ssh_pass`` in the inventory. +This tells Ansible that you have a RouterOS device called ``router`` with IP ``192.168.2.1``. Ansible should use the :ansplugin:`ansible.netcommon.network_cli connection plugin <ansible.netcommon.network_cli#connection>` together with the the :ansplugin:`community.routeros.routeros cliconf plugin <community.routeros.routeros#cliconf>`. The credentials are stored as ``ansible_user`` and ``ansible_ssh_pass`` in the inventory. Connecting to the device ------------------------ |