mirror.MikroTik/ansible-collections.community.routeros
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.routeros.git synced 2025-07-21 11:24:47 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

deploy: adff9bbf8c

Browse source
This commit is contained in:
felixfontein 2023-08-21 20:13:03 +00:00
parent 90f44f692d
commit ce40b34e16
24 changed files with 281 additions and 240 deletions
Download patch file Download diff file Expand all files Collapse all files

20
branch/main/docsite/api-guide.html
View file

@ -14,11 +14,11 @@
<script src="../_static/js/html5shiv.min.js"></script>
<![endif]-->
<script src="../_static/jquery.js"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/sphinx_highlight.js"></script>
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=7f41d439"></script>
<script src="../_static/doctools.js?v=888ff710"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/js/theme.js"></script>
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="How to connect to RouterOS devices with SSH" href="ssh-guide.html" />
@ -134,7 +134,7 @@
<div itemprop="articleBody">
<section id="how-to-connect-to-routeros-devices-with-the-routeros-api">
<span id="ansible-collections-community-routeros-docsite-api-guide"></span><h1>How to connect to RouterOS devices with the RouterOS API<a class="headerlink" href="#how-to-connect-to-routeros-devices-with-the-routeros-api" title="Permalink to this heading"></a></h1>
<span id="ansible-collections-community-routeros-docsite-api-guide"></span><h1>How to connect to RouterOS devices with the RouterOS API<a class="headerlink" href="#how-to-connect-to-routeros-devices-with-the-routeros-api" title="Link to this heading"></a></h1>
<p>You can use the <a class="reference internal" href="../api_module.html#ansible-collections-community-routeros-api-module"><span class="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 <a class="reference internal" href="../api_modify_module.html#ansible-collections-community-routeros-api-modify-module"><span class="std std-ref">community.routeros.api_modify</span></a> and <a class="reference internal" href="../api_find_and_modify_module.html#ansible-collections-community-routeros-api-find-and-modify-module"><span class="std std-ref">community.routeros.api_find_and_modify</span></a> modules. The <a class="reference internal" href="../api_info_module.html#ansible-collections-community-routeros-api-info-module"><span class="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 <code class="docutils literal notranslate"><span class="pre">community.routeros.api_modify</span></code> module, and the <a class="reference internal" href="../api_facts_module.html#ansible-collections-community-routeros-api-facts-module"><span class="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 <code class="docutils literal notranslate"><span class="pre">localhost</span></code>, either by using <code class="docutils literal notranslate"><span class="pre">hosts:</span> <span class="pre">localhost</span></code> in the playbook, or by using <code class="docutils literal notranslate"><span class="pre">delegate_to:</span> <span class="pre">localhost</span></code> for the task. The following example shows how to run the equivalent of <code class="docutils literal notranslate"><span class="pre">/ip</span> <span class="pre">address</span> <span class="pre">print</span></code>:</p>
<div class="highlight-yaml+jinja notranslate"><div class="highlight"><pre><span></span><span class="nn">---</span>
@ -183,7 +183,7 @@
</div>
<p>Check out the documenation of the <a class="reference internal" href="../api_module.html#ansible-collections-community-routeros-api-module"><span class="std std-ref">community.routeros.api module</span></a> for details on the options.</p>
<section id="using-the-community-routeros-api-module-defaults-group">
<h2>Using the <code class="docutils literal notranslate"><span class="pre">community.routeros.api</span></code> module defaults group<a class="headerlink" href="#using-the-community-routeros-api-module-defaults-group" title="Permalink to this heading"></a></h2>
<h2>Using the <code class="docutils literal notranslate"><span class="pre">community.routeros.api</span></code> module defaults group<a class="headerlink" href="#using-the-community-routeros-api-module-defaults-group" title="Link 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 <code class="docutils literal notranslate"><span class="pre">community.routeros.api</span></code> module defaults group:</p>
<div class="highlight-yaml+jinja notranslate"><div class="highlight"><pre><span></span><span class="nn">---</span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">RouterOS test with API</span>
@ -221,7 +221,7 @@
<p>Here all three tasks will use the options set for the module defaults group.</p>
</section>
<section id="setting-up-encryption">
<h2>Setting up encryption<a class="headerlink" href="#setting-up-encryption" title="Permalink to this heading"></a></h2>
<h2>Setting up encryption<a class="headerlink" href="#setting-up-encryption" title="Link to this heading"></a></h2>
<p>It is recommended to always use <code class="ansible-option-value docutils literal notranslate"><span><span class="pre">tls=true</span></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>
<dl class="field-list simple">
<dt class="field-odd">force_no_cert<span class="colon">:</span></dt>
@ -239,11 +239,11 @@
</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>
<section id="setting-up-a-pki">
<h3>Setting up a PKI<a class="headerlink" href="#setting-up-a-pki" title="Permalink to this heading"></a></h3>
<h3>Setting up a PKI<a class="headerlink" href="#setting-up-a-pki" title="Link to this heading"></a></h3>
<p>Please follow the instructions in the <code class="docutils literal notranslate"><span class="pre">community.crypto</span></code> <a class="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 <code class="docutils literal notranslate"><span class="pre">IP:192.168.1.1</span></code>) and - if available - for the DNS name (for example <code class="docutils literal notranslate"><span class="pre">DNS:router.local</span></code>) to the certificate.</p>
</section>
<section id="installing-a-certificate-on-a-mikrotik-router">
<h3>Installing a certificate on a MikroTik router<a class="headerlink" href="#installing-a-certificate-on-a-mikrotik-router" title="Permalink to this heading"></a></h3>
<h3>Installing a certificate on a MikroTik router<a class="headerlink" href="#installing-a-certificate-on-a-mikrotik-router" title="Link to this heading"></a></h3>
<p>Installing the certificate is best done with the SSH connection. (See the <a class="reference internal" href="ssh-guide.html#ansible-collections-community-routeros-docsite-ssh-guide"><span class="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 <a class="reference external" href="https://en.wikipedia.org/wiki/PKCS_12">PKCS #12 bundle</a>. This can be done with the <a class="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)"><span class="xref std std-ref">community.crypto.openssl_pkcs12</span></a>. The following playbook assumes that the certificate is available as <code class="docutils literal notranslate"><span class="pre">keys/{{</span> <span class="pre">inventory_hostname</span> <span class="pre">}}.pem</span></code>, and its private key is available as <code class="docutils literal notranslate"><span class="pre">keys/{{</span> <span class="pre">inventory_hostname</span> <span class="pre">}}.key</span></code>. It generates a random passphrase to protect the PKCS#12 file.</p>
<div class="highlight-yaml+jinja notranslate"><div class="highlight"><pre><span></span><span class="nn">---</span>

12
branch/main/docsite/quoting.html
View file

@ -14,11 +14,11 @@
<script src="../_static/js/html5shiv.min.js"></script>
<![endif]-->
<script src="../_static/jquery.js"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/sphinx_highlight.js"></script>
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=7f41d439"></script>
<script src="../_static/doctools.js?v=888ff710"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/js/theme.js"></script>
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="community.routeros.api module – Ansible module for RouterOS API" href="../api_module.html" />
@ -126,7 +126,7 @@
<div itemprop="articleBody">
<section id="how-to-quote-and-unquote-commands-and-arguments">
<span id="ansible-collections-community-routeros-docsite-quoting"></span><h1>How to quote and unquote commands and arguments<a class="headerlink" href="#how-to-quote-and-unquote-commands-and-arguments" title="Permalink to this heading"></a></h1>
<span id="ansible-collections-community-routeros-docsite-quoting"></span><h1>How to quote and unquote commands and arguments<a class="headerlink" href="#how-to-quote-and-unquote-commands-and-arguments" title="Link to this heading"></a></h1>
<p>When using the <a class="reference internal" href="../command_module.html#ansible-collections-community-routeros-command-module"><span class="std std-ref">community.routeros.command module</span></a> or the <a class="reference internal" href="../api_module.html#ansible-collections-community-routeros-api-module"><span class="std std-ref">community.routeros.api module</span></a> 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.</p>
<p>The community.routeros collection provides a set of Jinja2 filter plugins which helps you with these tasks:</p>
<ul class="simple">

18
branch/main/docsite/ssh-guide.html
View file

@ -14,11 +14,11 @@
<script src="../_static/js/html5shiv.min.js"></script>
<![endif]-->
<script src="../_static/jquery.js"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/sphinx_highlight.js"></script>
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=7f41d439"></script>
<script src="../_static/doctools.js?v=888ff710"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/js/theme.js"></script>
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="How to quote and unquote commands and arguments" href="quoting.html" />
@ -131,7 +131,7 @@
<div itemprop="articleBody">
<section id="how-to-connect-to-routeros-devices-with-ssh">
<span id="ansible-collections-community-routeros-docsite-ssh-guide"></span><h1>How to connect to RouterOS devices with SSH<a class="headerlink" href="#how-to-connect-to-routeros-devices-with-ssh" title="Permalink to this heading"></a></h1>
<span id="ansible-collections-community-routeros-docsite-ssh-guide"></span><h1>How to connect to RouterOS devices with SSH<a class="headerlink" href="#how-to-connect-to-routeros-devices-with-ssh" title="Link to this heading"></a></h1>
<p>The collection offers two modules to connect to RouterOS devies with SSH:</p>
<ul class="simple">
<li><p>The <a class="reference internal" href="../facts_module.html#ansible-collections-community-routeros-facts-module"><span class="std std-ref">community.routeros.facts module</span></a> gathers facts about a RouterOS device;</p></li>
@ -139,7 +139,7 @@
</ul>
<p>The modules need the <a class="reference external" href="https://docs.ansible.com/ansible/devel/collections/ansible/netcommon/network_cli_connection.html#ansible-collections-ansible-netcommon-network-cli-connection" title="(in Ansible vdevel)"><span class="xref std std-ref">ansible.netcommon.network_cli connection plugin</span></a> for this.</p>
<section id="important-notes">
<h2>Important notes<a class="headerlink" href="#important-notes" title="Permalink to this heading"></a></h2>
<h2>Important notes<a class="headerlink" href="#important-notes" title="Link to this heading"></a></h2>
<ol class="arabic">
<li><p>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 (<a class="reference external" href="https://github.com/ansible-collections/community.routeros/issues/31">see issue for details</a>). Similar problems can happen for unsupported characters in your username.</p></li>
<li><p>The <a class="reference internal" href="../command_module.html#ansible-collections-community-routeros-command-module"><span class="std std-ref">community.routeros.command module</span></a> does not support nesting commands and expects every command to start with a forward slash (<code class="docutils literal notranslate"><span class="pre">/</span></code>). Running the following command will produce an error:</p>
@ -155,7 +155,7 @@
</ol>
</section>
<section id="setting-up-an-inventory">
<h2>Setting up an inventory<a class="headerlink" href="#setting-up-an-inventory" title="Permalink to this heading"></a></h2>
<h2>Setting up an inventory<a class="headerlink" href="#setting-up-an-inventory" title="Link to this heading"></a></h2>
<p>An example inventory <code class="docutils literal notranslate"><span class="pre">hosts</span></code> file for a RouterOS device is as follows:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[routers]</span>
<span class="na">router ansible_host</span><span class="o">=</span><span class="s">192.168.2.1</span>
@ -170,7 +170,7 @@
<p>This tells Ansible that you have a RouterOS device called <code class="docutils literal notranslate"><span class="pre">router</span></code> with IP <code class="docutils literal notranslate"><span class="pre">192.168.2.1</span></code>. Ansible should use the <a class="reference external" href="https://docs.ansible.com/ansible/devel/collections/ansible/netcommon/network_cli_connection.html#ansible-collections-ansible-netcommon-network-cli-connection" title="(in Ansible vdevel)"><span class="xref std std-ref">ansible.netcommon.network_cli connection plugin</span></a> together with the the <a class="reference internal" href="../routeros_cliconf.html#ansible-collections-community-routeros-routeros-cliconf"><span class="std std-ref">community.routeros.routeros cliconf plugin</span></a>. The credentials are stored as <code class="docutils literal notranslate"><span class="pre">ansible_user</span></code> and <code class="docutils literal notranslate"><span class="pre">ansible_ssh_pass</span></code> in the inventory.</p>
</section>
<section id="connecting-to-the-device">
<h2>Connecting to the device<a class="headerlink" href="#connecting-to-the-device" title="Permalink to this heading"></a></h2>
<h2>Connecting to the device<a class="headerlink" href="#connecting-to-the-device" title="Link to this heading"></a></h2>
<p>With the above inventory, you can use the following playbook to execute <code class="docutils literal notranslate"><span class="pre">/system</span> <span class="pre">resource</span> <span class="pre">print</span></code> on the device</p>
<div class="highlight-yaml+jinja notranslate"><div class="highlight"><pre><span></span><span class="nn">---</span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">RouterOS test with network_cli connection</span>