<liclass="toctree-l1 current"><aclass="current reference internal"href="#">How to connect to RouterOS devices with the RouterOS API</a><ul>
<liclass="toctree-l2"><aclass="reference internal"href="#using-the-community-routeros-api-module-defaults-group">Using the <codeclass="docutils literal notranslate"><spanclass="pre">community.routeros.api</span></code> module defaults group</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="#setting-up-encryption">Setting up encryption</a><ul>
<liclass="toctree-l3"><aclass="reference internal"href="#setting-up-a-pki">Setting up a PKI</a></li>
<liclass="toctree-l3"><aclass="reference internal"href="#installing-a-certificate-on-a-mikrotik-router">Installing a certificate on a MikroTik router</a></li>
</ul>
</li>
</ul>
</li>
<liclass="toctree-l1"><aclass="reference internal"href="ssh-guide.html">How to connect to RouterOS devices with SSH</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="quoting.html">How to quote and unquote commands and arguments</a></li>
</ul>
<ul>
<liclass="toctree-l1"><aclass="reference internal"href="../api_module.html">community.routeros.api module – Ansible module for RouterOS API</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../api_facts_module.html">community.routeros.api_facts module – Collect facts from remote devices running MikroTik RouterOS using the API</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../api_find_and_modify_module.html">community.routeros.api_find_and_modify module – Find and modify information using the API</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../api_info_module.html">community.routeros.api_info module – Retrieve information from API</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../api_modify_module.html">community.routeros.api_modify module – Modify data at paths with API</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../command_module.html">community.routeros.command module – Run commands on remote devices running MikroTik RouterOS</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../routeros_cliconf.html">community.routeros.routeros cliconf – Use routeros cliconf to run command on MikroTik RouterOS platform</a></li>
</ul>
<ul>
<liclass="toctree-l1"><aclass="reference internal"href="../join_filter.html">community.routeros.join filter – Join a list of arguments to a command</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../list_to_dict_filter.html">community.routeros.list_to_dict filter – Convert a list of arguments to a dictionary</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../quote_argument_filter.html">community.routeros.quote_argument filter – Quote an argument</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../quote_argument_value_filter.html">community.routeros.quote_argument_value filter – Quote an argument value</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../split_filter.html">community.routeros.split filter – Split a command into arguments</a></li>
<spanid="ansible-collections-community-routeros-docsite-api-guide"></span><h1>How to connect to RouterOS devices with the RouterOS API<aclass="headerlink"href="#how-to-connect-to-routeros-devices-with-the-routeros-api"title="Permalink to this heading"></a></h1>
<p>You can use the <aclass="reference internal"href="../api_module.html#ansible-collections-community-routeros-api-module"><spanclass="std std-ref">community.routeros.api module</span></a> to connect to a RouterOS device with the RouterOS API. More specific module to modify certain entries are the <aclass="reference internal"href="../api_modify_module.html#ansible-collections-community-routeros-api-modify-module"><spanclass="std std-ref">community.routeros.api_modify</span></a> and <aclass="reference internal"href="../api_find_and_modify_module.html#ansible-collections-community-routeros-api-find-and-modify-module"><spanclass="std std-ref">community.routeros.api_find_and_modify</span></a> modules. The <aclass="reference internal"href="../api_info_module.html#ansible-collections-community-routeros-api-info-module"><spanclass="std std-ref">community.routeros.api_info module</span></a> allows to retrieve information on specific predefined paths that can be used as input for the <codeclass="docutils literal notranslate"><spanclass="pre">community.routeros.api_modify</span></code> module, and the <aclass="reference internal"href="../api_facts_module.html#ansible-collections-community-routeros-api-facts-module"><spanclass="std std-ref">community.routeros.api_facts module</span></a> allows to retrieve Ansible facts using the RouterOS API.</p>
<p>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 <codeclass="docutils literal notranslate"><spanclass="pre">localhost</span></code>, either by using <codeclass="docutils literal notranslate"><spanclass="pre">hosts:</span><spanclass="pre">localhost</span></code> in the playbook, or by using <codeclass="docutils literal notranslate"><spanclass="pre">delegate_to:</span><spanclass="pre">localhost</span></code> for the task. The following example shows how to run the equivalent of <codeclass="docutils literal notranslate"><spanclass="pre">/ip</span><spanclass="pre">address</span><spanclass="pre">print</span></code>:</p>
<spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="nt">name</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">RouterOS test with API</span>
<spanclass="w"></span><spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="nt">name</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">Show IP address of first interface</span>
<spanclass="k">TASK</span><spanclass="p">[</span><spanclass="l">Show IP address of first interface</span><spanclass="p">]</span><spanclass="nv">************************************************************************</span>
<p>Check out the documenation of the <aclass="reference internal"href="../api_module.html#ansible-collections-community-routeros-api-module"><spanclass="std std-ref">community.routeros.api module</span></a> for details on the options.</p>
<h2>Using the <codeclass="docutils literal notranslate"><spanclass="pre">community.routeros.api</span></code> module defaults group<aclass="headerlink"href="#using-the-community-routeros-api-module-defaults-group"title="Permalink to this heading"></a></h2>
<p>To avoid having to specify common parameters for all the API based modules in every task, you can use the <codeclass="docutils literal notranslate"><spanclass="pre">community.routeros.api</span></code> module defaults group:</p>
<spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="nt">name</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">RouterOS test with API</span>
<spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain"># The following options configure TLS/SSL.</span>
<spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain"># Depending on your setup, these options need different values</span><spanclass="p p-Indicator">:</span>
<spanclass="w"></span><spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="nt">name</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">Change IP address to 192.168.1.1 for interface bridge</span>
<p>It is recommended to always use <codeclass="ansible-option-value docutils literal notranslate"><spanclass="pre">tls=true</span></code> 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:</p>
<ddclass="field-odd"><p>Setting to <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">true</span></code> connects to the device without a certificate. <strong>This is discouraged to use in production and is susceptible to Man-in-the-Middle attacks</strong>, but might be useful when setting the device up. The default value is <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">false</span></code>.</p>
<ddclass="field-even"><p>Setting to <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">false</span></code> disables any certificate validation. <strong>This is discouraged to use in production</strong>, but is needed when setting the device up. The default value is <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">true</span></code>.</p>
<ddclass="field-odd"><p>Setting to <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">false</span></code> (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 <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">true</span></code>; the default <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">false</span></code> is chosen for backwards compatibility to an older version of the module.</p>
<ddclass="field-even"><p>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.</p>
</dd>
</dl>
<p>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.</p>
<sectionid="setting-up-a-pki">
<h3>Setting up a PKI<aclass="headerlink"href="#setting-up-a-pki"title="Permalink to this heading"></a></h3>
<p>Please follow the instructions in the <codeclass="docutils literal notranslate"><spanclass="pre">community.crypto</span></code><aclass="reference external"href="https://docs.ansible.com/ansible/devel/collections/community/crypto/docsite/guide_ownca.html#ansible-collections-community-crypto-docsite-guide-ownca"title="(in Ansible vdevel)"><span>How to create a small CA</span></a> guide to set up a CA certificate and sign a certificate for your router. You should add a Subject Alternative Name for the IP address (for example <codeclass="docutils literal notranslate"><spanclass="pre">IP:192.168.1.1</span></code>) and - if available - for the DNS name (for example <codeclass="docutils literal notranslate"><spanclass="pre">DNS:router.local</span></code>) to the certificate.</p>
<h3>Installing a certificate on a MikroTik router<aclass="headerlink"href="#installing-a-certificate-on-a-mikrotik-router"title="Permalink to this heading"></a></h3>
<p>Installing the certificate is best done with the SSH connection. (See the <aclass="reference internal"href="ssh-guide.html#ansible-collections-community-routeros-docsite-ssh-guide"><spanclass="std std-ref">How to connect to RouterOS devices with SSH</span></a> 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.</p>
<p>First you have to convert the certificate and its private key to a <aclass="reference external"href="https://en.wikipedia.org/wiki/PKCS_12">PKCS #12 bundle</a>. This can be done with the <aclass="reference external"href="https://docs.ansible.com/ansible/devel/collections/community/crypto/openssl_pkcs12_module.html#ansible-collections-community-crypto-openssl-pkcs12-module"title="(in Ansible vdevel)"><spanclass="xref std std-ref">community.crypto.openssl_pkcs12</span></a>. The following playbook assumes that the certificate is available as <codeclass="docutils literal notranslate"><spanclass="pre">keys/{{</span><spanclass="pre">inventory_hostname</span><spanclass="pre">}}.pem</span></code>, and its private key is available as <codeclass="docutils literal notranslate"><spanclass="pre">keys/{{</span><spanclass="pre">inventory_hostname</span><spanclass="pre">}}.key</span></code>. It generates a random passphrase to protect the PKCS#12 file.</p>
<spanclass="w"></span><spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="nt">name</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">Show result of certificate import</span>
<p>The playbook also assumes that <codeclass="docutils literal notranslate"><spanclass="pre">admin_network</span></code> describes the network from which the HTTPS and API interface can be accessed. This can be for example <codeclass="docutils literal notranslate"><spanclass="pre">192.168.1.0/24</span></code>.</p>
<p>When this playbook completed successfully, you should be able to use the HTTPS admin interface (reachable in a browser from <codeclass="docutils literal notranslate"><spanclass="pre">https://192.168.1.1/</span></code>, with the correct IP inserted), as well as the <aclass="reference internal"href="../api_module.html#ansible-collections-community-routeros-api-module"><spanclass="std std-ref">community.routeros.api module</span></a> module with TLS and certificate validation enabled:</p>
<ahref="ssh-guide.html"class="btn btn-neutral float-right"title="How to connect to RouterOS devices with SSH"accesskey="n"rel="next">Next <spanclass="fa fa-arrow-circle-right"aria-hidden="true"></span></a>
