mirror.MikroTik/ansible-collections.community.routeros
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.routeros.git synced 2025-08-03 17:55:12 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

deploy: 26e3aa3e0a

Browse source
This commit is contained in:
felixfontein 2024-10-19 10:26:07 +00:00
parent 4395bf7786
commit 91c00c3ff7
87 changed files with 14551 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

352
branch/stable-2/docsite/api-guide.html Normal file
View file

@ -0,0 +1,352 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>How to connect to RouterOS devices with the RouterOS API &mdash; Community.Routeros Collection documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=5707b69d" />
<link rel="stylesheet" type="text/css" href="../_static/css/ansible.css?v=c5b67dd2" />
<link rel="stylesheet" type="text/css" href="../_static/antsibull-minimal.css" />
<link rel="stylesheet" type="text/css" href="../_static/css/rtd-ethical-ads.css?v=289b023e" />
<link rel="shortcut icon" href="../_static/images/Ansible-Mark-RGB_Black.png"/>
<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=9bcbadda"></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" />
<link rel="prev" title="Community.Routeros Release Notes" href="../changelog.html" /><!-- extra head elements for Ansible beyond RTD Sphinx Theme -->
</head>
<body class="wy-body-for-nav"><!-- extra body elements for Ansible beyond RTD Sphinx Theme -->
<div class="DocSite-globalNav ansibleNav">
<ul>
<li><a href="https://www.ansible.com/blog" target="_blank">Blog</a></li>
<li><a href="https://forum.ansible.com/" target="_blank">Ansible community forum</a></li>
<li><a href="https://docs.ansible.com/" target="_blank">Documentation</a></li>
</ul>
</div>
<a class="DocSite-nav" href="https://ansible-collections.github.io/community.routeros/branch/main/" style="padding-bottom: 30px;">
<img class="DocSiteNav-logo"
src="../_static/images/Ansible-Mark-RGB_White.png"
alt="Ansible Logo">
<div class="DocSiteNav-title">Community.Routeros Collection Docs</div>
</a>
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
Community.Routeros Collection
</a><!--- Based on https://github.com/rtfd/sphinx_rtd_theme/pull/438/files -->
<div class="version">
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<label class="sr-only" for="q">Search docs:</label>
<input type="text" class="st-default-search-input" id="q" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../changelog.html">Community.Routeros Release Notes</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">How to connect to RouterOS devices with the RouterOS API</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#using-the-community-routeros-api-module-defaults-group">Using the <code class="docutils literal notranslate"><span class="pre">community.routeros.api</span></code> module defaults group</a></li>
<li class="toctree-l2"><a class="reference internal" href="#setting-up-encryption">Setting up encryption</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#setting-up-a-pki">Setting up a PKI</a></li>
<li class="toctree-l3"><a class="reference internal" href="#installing-a-certificate-on-a-mikrotik-router">Installing a certificate on a MikroTik router</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ssh-guide.html">How to connect to RouterOS devices with SSH</a></li>
<li class="toctree-l1"><a class="reference internal" href="quoting.html">How to quote and unquote commands and arguments</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../api_module.html">community.routeros.api module – Ansible module for RouterOS API</a></li>
<li class="toctree-l1"><a class="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>
<li class="toctree-l1"><a class="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>
<li class="toctree-l1"><a class="reference internal" href="../api_info_module.html">community.routeros.api_info module – Retrieve information from API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../api_modify_module.html">community.routeros.api_modify module – Modify data at paths with API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../command_module.html">community.routeros.command module – Run commands on remote devices running MikroTik RouterOS</a></li>
<li class="toctree-l1"><a class="reference internal" href="../facts_module.html">community.routeros.facts module – Collect facts from remote devices running MikroTik RouterOS</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../routeros_cliconf.html">community.routeros.routeros cliconf – Use routeros cliconf to run command on MikroTik RouterOS platform</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../join_filter.html">community.routeros.join filter – Join a list of arguments to a command</a></li>
<li class="toctree-l1"><a class="reference internal" href="../list_to_dict_filter.html">community.routeros.list_to_dict filter – Convert a list of arguments to a dictionary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../quote_argument_filter.html">community.routeros.quote_argument filter – Quote an argument</a></li>
<li class="toctree-l1"><a class="reference internal" href="../quote_argument_value_filter.html">community.routeros.quote_argument_value filter – Quote an argument value</a></li>
<li class="toctree-l1"><a class="reference internal" href="../split_filter.html">community.routeros.split filter – Split a command into arguments</a></li>
</ul>
<!-- extra nav elements for Ansible beyond RTD Sphinx Theme -->
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Community.Routeros Collection</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">How to connect to RouterOS devices with the RouterOS API</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<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="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 <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> 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>
<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>
<span class="w"> </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">localhost</span>
<span class="w"> </span><span class="nt">gather_facts</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
<span class="w"> </span><span class="nt">vars</span><span class="p">:</span>
<span class="w"> </span><span class="nt">hostname</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.168.1.1</span>
<span class="w"> </span><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">admin</span>
<span class="w"> </span><span class="nt">password</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">test1234</span>
<span class="w"> </span><span class="nt">tasks</span><span class="p">:</span>
<span class="w"> </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">Get &quot;ip address print&quot;</span>
<span class="w"> </span><span class="nt">community.routeros.api</span><span class="p">:</span>
<span class="w"> </span><span class="nt">hostname</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;</span><span class="cp">{{</span> <span class="nv">hostname</span> <span class="cp">}}</span><span class="s">&quot;</span>
<span class="w"> </span><span class="nt">password</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;</span><span class="cp">{{</span> <span class="nv">password</span> <span class="cp">}}</span><span class="s">&quot;</span>
<span class="w"> </span><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;</span><span class="cp">{{</span> <span class="nv">username</span> <span class="cp">}}</span><span class="s">&quot;</span>
<span class="w"> </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;ip</span><span class="nv"> </span><span class="s">address&quot;</span>
<span class="w"> </span><span class="c1"># The following options configure TLS/SSL.</span>
<span class="w"> </span><span class="c1"># Depending on your setup, these options need different values:</span>
<span class="w"> </span><span class="nt">tls</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="nt">validate_certs</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="nt">validate_cert_hostname</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="c1"># If you are using your own PKI, specify the path to your CA certificate here:</span>
<span class="w"> </span><span class="c1"># ca_path: /path/to/ca-certificate.pem</span>
<span class="w"> </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">print_path</span>
<span class="w"> </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">Show IP address of first interface</span>
<span class="w"> </span><span class="nt">ansible.builtin.debug</span><span class="p">:</span>
<span class="w"> </span><span class="nt">msg</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;</span><span class="cp">{{</span> <span class="nv">print_path.msg</span><span class="o">[</span><span class="m">0</span><span class="o">]</span><span class="nv">.address</span> <span class="cp">}}</span><span class="s">&quot;</span>
</pre></div>
</div>
<p>This results in the following output:</p>
<div class="highlight-ansible-output notranslate"><div class="highlight"><pre><span></span><span class="k">PLAY</span> <span class="p">[</span><span class="l">RouterOS test</span><span class="p">]</span> <span class="nv">*********************************************************************************************</span>
<span class="k">TASK</span> <span class="p">[</span><span class="l">Get &quot;ip address print&quot;</span><span class="p">]</span> <span class="nv">************************************************************************************</span>
<span class="k">ok</span><span class="p">:</span> <span class="p">[</span><span class="nv">localhost</span><span class="p">]</span>
<span class="k">TASK</span> <span class="p">[</span><span class="l">Show IP address of first interface</span><span class="p">]</span> <span class="nv">************************************************************************</span>
<span class="k">ok</span><span class="p">:</span> <span class="p">[</span><span class="nv">localhost</span><span class="p">]</span> <span class="p">=&gt;</span> <span class="p">{</span>
<span class="nt">&quot;msg&quot;</span><span class="p">:</span> <span class="s">&quot;192.168.2.1/24&quot;</span>
<span class="p">}</span>
<span class="k">PLAY RECAP</span> <span class="nv">*******************************************************************************************************</span>
<span class="n">localhost</span> <span class="p">:</span> <span class="k">ok</span><span class="p">=</span><span class="mi">2</span> <span class="k">changed</span><span class="p">=</span><span class="mi">0</span> <span class="k">unreachable</span><span class="p">=</span><span class="mi">0</span> <span class="k">failed</span><span class="p">=</span><span class="mi">0</span> <span class="k">skipped</span><span class="p">=</span><span class="mi">0</span> <span class="k">rescued</span><span class="p">=</span><span class="mi">0</span> <span class="k">ignored</span><span class="p">=</span><span class="mi">0</span>
</pre></div>
</div>
<p>Check out the documentation 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="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> <a class="reference external" href="https://docs.ansible.com/ansible/devel/playbook_guide/playbooks_module_defaults.html#module-defaults-groups" title="(in Ansible vdevel)"><span class="xref std std-ref">module defaults group</span></a>:</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>
<span class="w"> </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">localhost</span>
<span class="w"> </span><span class="nt">gather_facts</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
<span class="w"> </span><span class="nt">module_defaults</span><span class="p">:</span>
<span class="w"> </span><span class="nt">group/community.routeros.api</span><span class="p">:</span>
<span class="w"> </span><span class="nt">hostname</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.168.1.1</span>
<span class="w"> </span><span class="nt">password</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">admin</span>
<span class="w"> </span><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">test1234</span>
<span class="w"> </span><span class="c1"># The following options configure TLS/SSL.</span>
<span class="w"> </span><span class="c1"># Depending on your setup, these options need different values:</span>
<span class="w"> </span><span class="nt">tls</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="nt">validate_certs</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="nt">validate_cert_hostname</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="c1"># If you are using your own PKI, specify the path to your CA certificate here:</span>
<span class="w"> </span><span class="c1"># ca_path: /path/to/ca-certificate.pem</span>
<span class="w"> </span><span class="nt">tasks</span><span class="p">:</span>
<span class="w"> </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">Gather facts</span>
<span class="w"> </span><span class="nt">community.routeros.api_facts</span><span class="p">:</span>
<span class="w"> </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">Get &quot;ip address print&quot;</span>
<span class="w"> </span><span class="nt">community.routeros.api</span><span class="p">:</span>
<span class="w"> </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;ip</span><span class="nv"> </span><span class="s">address&quot;</span>
<span class="w"> </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">Change IP address to 192.168.1.1 for interface bridge</span>
<span class="w"> </span><span class="nt">community.routeros.api_find_and_modify</span><span class="p">:</span>
<span class="w"> </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ip address</span>
<span class="w"> </span><span class="nt">find</span><span class="p">:</span>
<span class="w"> </span><span class="nt">interface</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bridge</span>
<span class="w"> </span><span class="nt">values</span><span class="p">:</span>
<span class="w"> </span><span class="nt">address</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;192.168.1.1/24&quot;</span>
</pre></div>
</div>
<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="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>
<dd class="field-odd"><p>Setting to <code class="ansible-value docutils literal notranslate"><span class="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 <code class="ansible-value docutils literal notranslate"><span class="pre">false</span></code>.</p>
</dd>
<dt class="field-even">validate_certs<span class="colon">:</span></dt>
<dd class="field-even"><p>Setting to <code class="ansible-value docutils literal notranslate"><span class="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 <code class="ansible-value docutils literal notranslate"><span class="pre">true</span></code>.</p>
</dd>
<dt class="field-odd">validate_cert_hostname<span class="colon">:</span></dt>
<dd class="field-odd"><p>Setting to <code class="ansible-value docutils literal notranslate"><span class="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 <code class="ansible-value docutils literal notranslate"><span class="pre">true</span></code>; the default <code class="ansible-value docutils literal notranslate"><span class="pre">false</span></code> is chosen for backwards compatibility to an older version of the module.</p>
</dd>
<dt class="field-even">ca_path<span class="colon">:</span></dt>
<dd class="field-even"><p>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.</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>
<section id="setting-up-a-pki">
<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="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>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>
<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">Install certificates on devices</span>
<span class="w"> </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">routers</span>
<span class="w"> </span><span class="nt">gather_facts</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
<span class="w"> </span><span class="nt">tasks</span><span class="p">:</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">block</span><span class="p">:</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">set_fact</span><span class="p">:</span>
<span class="w"> </span><span class="nt">random_password</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;</span><span class="cp">{{</span> <span class="nv">lookup</span><span class="o">(</span><span class="s1">&#39;community.general.random_string&#39;</span><span class="o">,</span> <span class="nv">length</span><span class="o">=</span><span class="m">32</span><span class="o">,</span> <span class="nv">override_all</span><span class="o">=</span><span class="s1">&#39;0123456789abcdefghijklmnopqrstuvwxyz&#39;</span><span class="o">)</span> <span class="cp">}}</span><span class="s">&quot;</span>
<span class="w"> </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">Create PKCS#12 bundle</span>
<span class="w"> </span><span class="nt">openssl_pkcs12</span><span class="p">:</span>
<span class="w"> </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">keys/</span><span class="cp">{{</span> <span class="nv">inventory_hostname</span> <span class="cp">}}</span><span class="l l-Scalar l-Scalar-Plain">.p12</span>
<span class="w"> </span><span class="nt">certificate_path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">keys/</span><span class="cp">{{</span> <span class="nv">inventory_hostname</span> <span class="cp">}}</span><span class="l l-Scalar l-Scalar-Plain">.pem</span>
<span class="w"> </span><span class="nt">privatekey_path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">keys/</span><span class="cp">{{</span> <span class="nv">inventory_hostname</span> <span class="cp">}}</span><span class="l l-Scalar l-Scalar-Plain">.key</span>
<span class="w"> </span><span class="nt">friendly_name</span><span class="p">:</span><span class="w"> </span><span class="s">&#39;</span><span class="cp">{{</span> <span class="nv">inventory_hostname</span> <span class="cp">}}</span><span class="s">&#39;</span>
<span class="w"> </span><span class="nt">passphrase</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;</span><span class="cp">{{</span> <span class="nv">random_password</span> <span class="cp">}}</span><span class="s">&quot;</span>
<span class="w"> </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;0600&quot;</span>
<span class="w"> </span><span class="nt">changed_when</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
<span class="w"> </span><span class="nt">delegate_to</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">localhost</span>
<span class="w"> </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">Copy router certificate onto router</span>
<span class="w"> </span><span class="nt">ansible.netcommon.net_put</span><span class="p">:</span>
<span class="w"> </span><span class="nt">src</span><span class="p">:</span><span class="w"> </span><span class="s">&#39;keys/</span><span class="cp">{{</span> <span class="nv">inventory_hostname</span> <span class="cp">}}</span><span class="s">.p12&#39;</span>
<span class="w"> </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="s">&#39;</span><span class="cp">{{</span> <span class="nv">inventory_hostname</span> <span class="cp">}}</span><span class="s">.p12&#39;</span>
<span class="w"> </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">Install router certificate and clean up</span>
<span class="w"> </span><span class="nt">community.routeros.command</span><span class="p">:</span>
<span class="w"> </span><span class="nt">commands</span><span class="p">:</span>
<span class="w"> </span><span class="c1"># Import certificate:</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/certificate import name=</span><span class="cp">{{</span> <span class="nv">inventory_hostname</span> <span class="cp">}}</span><span class="l l-Scalar l-Scalar-Plain"> file-name=</span><span class="cp">{{</span> <span class="nv">inventory_hostname</span> <span class="cp">}}</span><span class="l l-Scalar l-Scalar-Plain">.p12 passphrase=&quot;</span><span class="cp">{{</span> <span class="nv">random_password</span> <span class="cp">}}</span><span class="l l-Scalar l-Scalar-Plain">&quot;</span>
<span class="w"> </span><span class="c1"># Remove PKCS12 bundle:</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/file remove </span><span class="cp">{{</span> <span class="nv">inventory_hostname</span> <span class="cp">}}</span><span class="l l-Scalar l-Scalar-Plain">.p12</span>
<span class="w"> </span><span class="c1"># Show certificates</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/certificate print</span>
<span class="w"> </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">output</span>
<span class="w"> </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">Show result of certificate import</span>
<span class="w"> </span><span class="nt">debug</span><span class="p">:</span>
<span class="w"> </span><span class="nt">var</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">output.stdout_lines[0]</span>
<span class="w"> </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">Show certificates</span>
<span class="w"> </span><span class="nt">debug</span><span class="p">:</span>
<span class="w"> </span><span class="nt">var</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">output.stdout_lines[2]</span>
<span class="w"> </span><span class="nt">always</span><span class="p">:</span>
<span class="w"> </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">Wipe PKCS12 bundle</span>
<span class="w"> </span><span class="nt">command</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">wipe keys/</span><span class="cp">{{</span> <span class="nv">inventory_hostname</span> <span class="cp">}}</span><span class="l l-Scalar l-Scalar-Plain">.p12</span>
<span class="w"> </span><span class="nt">changed_when</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
<span class="w"> </span><span class="nt">delegate_to</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">localhost</span>
<span class="w"> </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">Use certificate</span>
<span class="w"> </span><span class="nt">community.routeros.command</span><span class="p">:</span>
<span class="w"> </span><span class="nt">commands</span><span class="p">:</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/ip service set www-ssl address=</span><span class="cp">{{</span> <span class="nv">admin_network</span> <span class="cp">}}</span><span class="l l-Scalar l-Scalar-Plain"> certificate=</span><span class="cp">{{</span> <span class="nv">inventory_hostname</span> <span class="cp">}}</span><span class="l l-Scalar l-Scalar-Plain"> disabled=no tls-version=only-1.2</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/ip service set api-ssl address=</span><span class="cp">{{</span> <span class="nv">admin_network</span> <span class="cp">}}</span><span class="l l-Scalar l-Scalar-Plain"> certificate=</span><span class="cp">{{</span> <span class="nv">inventory_hostname</span> <span class="cp">}}</span><span class="l l-Scalar l-Scalar-Plain"> tls-version=only-1.2</span>
</pre></div>
</div>
<p>The playbook also assumes that <code class="docutils literal notranslate"><span class="pre">admin_network</span></code> describes the network from which the HTTPS and API interface can be accessed. This can be for example <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">https://192.168.1.1/</span></code>, with the correct IP inserted), as well as 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> module with TLS and certificate validation enabled:</p>
<div class="highlight-yaml+jinja notranslate"><div class="highlight"><pre><span></span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">community.routeros.api</span><span class="p">:</span>
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">...</span>
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">tls</span><span class="p p-Indicator">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="nt">validate_certs</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="nt">validate_cert_hostname</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="nt">ca_path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/path/to/ca-certificate.pem</span>
</pre></div>
</div>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="../changelog.html" class="btn btn-neutral float-left" title="Community.Routeros Release Notes" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="ssh-guide.html" class="btn btn-neutral float-right" title="How to connect to RouterOS devices with SSH" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright Community.Routeros Contributors.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script><!-- extra footer elements for Ansible beyond RTD Sphinx Theme -->
</body>
</html>

173
branch/stable-2/docsite/quoting.html Normal file
View file

@ -0,0 +1,173 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>How to quote and unquote commands and arguments &mdash; Community.Routeros Collection documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=5707b69d" />
<link rel="stylesheet" type="text/css" href="../_static/css/ansible.css?v=c5b67dd2" />
<link rel="stylesheet" type="text/css" href="../_static/antsibull-minimal.css" />
<link rel="stylesheet" type="text/css" href="../_static/css/rtd-ethical-ads.css?v=289b023e" />
<link rel="shortcut icon" href="../_static/images/Ansible-Mark-RGB_Black.png"/>
<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=9bcbadda"></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" />
<link rel="prev" title="How to connect to RouterOS devices with SSH" href="ssh-guide.html" /><!-- extra head elements for Ansible beyond RTD Sphinx Theme -->
</head>
<body class="wy-body-for-nav"><!-- extra body elements for Ansible beyond RTD Sphinx Theme -->
<div class="DocSite-globalNav ansibleNav">
<ul>
<li><a href="https://www.ansible.com/blog" target="_blank">Blog</a></li>
<li><a href="https://forum.ansible.com/" target="_blank">Ansible community forum</a></li>
<li><a href="https://docs.ansible.com/" target="_blank">Documentation</a></li>
</ul>
</div>
<a class="DocSite-nav" href="https://ansible-collections.github.io/community.routeros/branch/main/" style="padding-bottom: 30px;">
<img class="DocSiteNav-logo"
src="../_static/images/Ansible-Mark-RGB_White.png"
alt="Ansible Logo">
<div class="DocSiteNav-title">Community.Routeros Collection Docs</div>
</a>
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
Community.Routeros Collection
</a><!--- Based on https://github.com/rtfd/sphinx_rtd_theme/pull/438/files -->
<div class="version">
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<label class="sr-only" for="q">Search docs:</label>
<input type="text" class="st-default-search-input" id="q" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../changelog.html">Community.Routeros Release Notes</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="api-guide.html">How to connect to RouterOS devices with the RouterOS API</a></li>
<li class="toctree-l1"><a class="reference internal" href="ssh-guide.html">How to connect to RouterOS devices with SSH</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">How to quote and unquote commands and arguments</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../api_module.html">community.routeros.api module – Ansible module for RouterOS API</a></li>
<li class="toctree-l1"><a class="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>
<li class="toctree-l1"><a class="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>
<li class="toctree-l1"><a class="reference internal" href="../api_info_module.html">community.routeros.api_info module – Retrieve information from API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../api_modify_module.html">community.routeros.api_modify module – Modify data at paths with API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../command_module.html">community.routeros.command module – Run commands on remote devices running MikroTik RouterOS</a></li>
<li class="toctree-l1"><a class="reference internal" href="../facts_module.html">community.routeros.facts module – Collect facts from remote devices running MikroTik RouterOS</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../routeros_cliconf.html">community.routeros.routeros cliconf – Use routeros cliconf to run command on MikroTik RouterOS platform</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../join_filter.html">community.routeros.join filter – Join a list of arguments to a command</a></li>
<li class="toctree-l1"><a class="reference internal" href="../list_to_dict_filter.html">community.routeros.list_to_dict filter – Convert a list of arguments to a dictionary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../quote_argument_filter.html">community.routeros.quote_argument filter – Quote an argument</a></li>
<li class="toctree-l1"><a class="reference internal" href="../quote_argument_value_filter.html">community.routeros.quote_argument_value filter – Quote an argument value</a></li>
<li class="toctree-l1"><a class="reference internal" href="../split_filter.html">community.routeros.split filter – Split a command into arguments</a></li>
</ul>
<!-- extra nav elements for Ansible beyond RTD Sphinx Theme -->
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Community.Routeros Collection</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">How to quote and unquote commands and arguments</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<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="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">
<li><p>The <a class="reference internal" href="../quote_argument_value_filter.html#ansible-collections-community-routeros-quote-argument-value-filter"><span class="std std-ref">community.routeros.quote_argument_value filter</span></a> quotes an argument value: <code class="docutils literal notranslate"><span class="pre">'this</span> <span class="pre">is</span> <span class="pre">a</span> <span class="pre">&quot;comment&quot;'</span> <span class="pre">|</span> <span class="pre">community.routeros.quote_argument_value</span> <span class="pre">==</span> <span class="pre">'&quot;this</span> <span class="pre">is</span> <span class="pre">a</span> <span class="pre">\\&quot;comment\\&quot;&quot;'</span></code>.</p></li>
<li><p>The <a class="reference internal" href="../quote_argument_filter.html#ansible-collections-community-routeros-quote-argument-filter"><span class="std std-ref">community.routeros.quote_argument filter</span></a> quotes an argument with or without a value: <code class="docutils literal notranslate"><span class="pre">'comment=this</span> <span class="pre">is</span> <span class="pre">a</span> <span class="pre">&quot;comment&quot;'</span> <span class="pre">|</span> <span class="pre">community.routeros.quote_argument</span> <span class="pre">==</span> <span class="pre">'comment=&quot;this</span> <span class="pre">is</span> <span class="pre">a</span> <span class="pre">\\&quot;comment\\&quot;&quot;'</span></code>.</p></li>
<li><p>The <a class="reference internal" href="../join_filter.html#ansible-collections-community-routeros-join-filter"><span class="std std-ref">community.routeros.join filter</span></a> quotes a list of arguments and joins them to one string: <code class="docutils literal notranslate"><span class="pre">['foo=bar',</span> <span class="pre">'comment=foo</span> <span class="pre">is</span> <span class="pre">bar']</span> <span class="pre">|</span> <span class="pre">community.routeros.join</span> <span class="pre">==</span> <span class="pre">'foo=bar</span> <span class="pre">comment=&quot;foo</span> <span class="pre">is</span> <span class="pre">bar&quot;'</span></code>.</p></li>
<li><p>The <a class="reference internal" href="../split_filter.html#ansible-collections-community-routeros-split-filter"><span class="std std-ref">community.routeros.split filter</span></a> splits a command into a list of arguments (with or without values): <code class="docutils literal notranslate"><span class="pre">'foo=bar</span> <span class="pre">comment=&quot;foo</span> <span class="pre">is</span> <span class="pre">bar&quot;'</span> <span class="pre">|</span> <span class="pre">community.routeros.split</span> <span class="pre">==</span> <span class="pre">['foo=bar',</span> <span class="pre">'comment=foo</span> <span class="pre">is</span> <span class="pre">bar']</span></code></p></li>
<li><p>The <a class="reference internal" href="../list_to_dict_filter.html#ansible-collections-community-routeros-list-to-dict-filter"><span class="std std-ref">community.routeros.list_to_dict filter</span></a> splits a list of arguments with values into a dictionary: <code class="docutils literal notranslate"><span class="pre">['foo=bar',</span> <span class="pre">'comment=foo</span> <span class="pre">is</span> <span class="pre">bar']</span> <span class="pre">|</span> <span class="pre">community.routeros.list_to_dict</span> <span class="pre">==</span> <span class="pre">{'foo':</span> <span class="pre">'bar',</span> <span class="pre">'comment':</span> <span class="pre">'foo</span> <span class="pre">is</span> <span class="pre">bar'}</span></code>. It has two optional arguments: <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="../list_to_dict_filter.html#ansible-collections-community-routeros-list-to-dict-filter-parameter-require-assignment"><span class="std std-ref"><span class="pre">require_assignment</span></span></a></strong></code> (default value <code class="ansible-value docutils literal notranslate"><span class="pre">true</span></code>) allows to accept arguments without values when set to <code class="ansible-value docutils literal notranslate"><span class="pre">false</span></code>; and <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="../list_to_dict_filter.html#ansible-collections-community-routeros-list-to-dict-filter-parameter-skip-empty-values"><span class="std std-ref"><span class="pre">skip_empty_values</span></span></a></strong></code> (default value <code class="ansible-value docutils literal notranslate"><span class="pre">false</span></code>) allows to skip arguments whose value is empty.</p></li>
</ul>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="ssh-guide.html" class="btn btn-neutral float-left" title="How to connect to RouterOS devices with SSH" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="../api_module.html" class="btn btn-neutral float-right" title="community.routeros.api module – Ansible module for RouterOS API" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright Community.Routeros Contributors.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script><!-- extra footer elements for Ansible beyond RTD Sphinx Theme -->
</body>
</html>

278
branch/stable-2/docsite/ssh-guide.html Normal file
View file

@ -0,0 +1,278 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>How to connect to RouterOS devices with SSH &mdash; Community.Routeros Collection documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=5707b69d" />
<link rel="stylesheet" type="text/css" href="../_static/css/ansible.css?v=c5b67dd2" />
<link rel="stylesheet" type="text/css" href="../_static/antsibull-minimal.css" />
<link rel="stylesheet" type="text/css" href="../_static/css/rtd-ethical-ads.css?v=289b023e" />
<link rel="shortcut icon" href="../_static/images/Ansible-Mark-RGB_Black.png"/>
<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=9bcbadda"></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" />
<link rel="prev" title="How to connect to RouterOS devices with the RouterOS API" href="api-guide.html" /><!-- extra head elements for Ansible beyond RTD Sphinx Theme -->
</head>
<body class="wy-body-for-nav"><!-- extra body elements for Ansible beyond RTD Sphinx Theme -->
<div class="DocSite-globalNav ansibleNav">
<ul>
<li><a href="https://www.ansible.com/blog" target="_blank">Blog</a></li>
<li><a href="https://forum.ansible.com/" target="_blank">Ansible community forum</a></li>
<li><a href="https://docs.ansible.com/" target="_blank">Documentation</a></li>
</ul>
</div>
<a class="DocSite-nav" href="https://ansible-collections.github.io/community.routeros/branch/main/" style="padding-bottom: 30px;">
<img class="DocSiteNav-logo"
src="../_static/images/Ansible-Mark-RGB_White.png"
alt="Ansible Logo">
<div class="DocSiteNav-title">Community.Routeros Collection Docs</div>
</a>
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
Community.Routeros Collection
</a><!--- Based on https://github.com/rtfd/sphinx_rtd_theme/pull/438/files -->
<div class="version">
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<label class="sr-only" for="q">Search docs:</label>
<input type="text" class="st-default-search-input" id="q" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../changelog.html">Community.Routeros Release Notes</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="api-guide.html">How to connect to RouterOS devices with the RouterOS API</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">How to connect to RouterOS devices with SSH</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#important-notes">Important notes</a></li>
<li class="toctree-l2"><a class="reference internal" href="#setting-up-an-inventory">Setting up an inventory</a></li>
<li class="toctree-l2"><a class="reference internal" href="#connecting-to-the-device">Connecting to the device</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="quoting.html">How to quote and unquote commands and arguments</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../api_module.html">community.routeros.api module – Ansible module for RouterOS API</a></li>
<li class="toctree-l1"><a class="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>
<li class="toctree-l1"><a class="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>
<li class="toctree-l1"><a class="reference internal" href="../api_info_module.html">community.routeros.api_info module – Retrieve information from API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../api_modify_module.html">community.routeros.api_modify module – Modify data at paths with API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../command_module.html">community.routeros.command module – Run commands on remote devices running MikroTik RouterOS</a></li>
<li class="toctree-l1"><a class="reference internal" href="../facts_module.html">community.routeros.facts module – Collect facts from remote devices running MikroTik RouterOS</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../routeros_cliconf.html">community.routeros.routeros cliconf – Use routeros cliconf to run command on MikroTik RouterOS platform</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../join_filter.html">community.routeros.join filter – Join a list of arguments to a command</a></li>
<li class="toctree-l1"><a class="reference internal" href="../list_to_dict_filter.html">community.routeros.list_to_dict filter – Convert a list of arguments to a dictionary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../quote_argument_filter.html">community.routeros.quote_argument filter – Quote an argument</a></li>
<li class="toctree-l1"><a class="reference internal" href="../quote_argument_value_filter.html">community.routeros.quote_argument_value filter – Quote an argument value</a></li>
<li class="toctree-l1"><a class="reference internal" href="../split_filter.html">community.routeros.split filter – Split a command into arguments</a></li>
</ul>
<!-- extra nav elements for Ansible beyond RTD Sphinx Theme -->
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Community.Routeros Collection</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">How to connect to RouterOS devices with SSH</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<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="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>
<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> executes commands on a RouterOS device.</p></li>
</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>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="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>
<div class="highlight-yaml+jinja notranslate"><div class="highlight"><pre><span></span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">community.routeros.command</span><span class="p">:</span>
<span class="w"> </span><span class="nt">commands</span><span class="p">:</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/ip</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">print</span>
</pre></div>
</div>
</li>
<li><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> module, make sure to not specify too long commands. Alternatively, add something like <code class="docutils literal notranslate"><span class="pre">+cet512w</span></code> to the username (replace <code class="docutils literal notranslate"><span class="pre">admin</span></code> with <code class="docutils literal notranslate"><span class="pre">admin+cet512w</span></code>) to tell RouterOS to not wrap before 512 characters in a line (<a class="reference external" href="https://github.com/ansible-collections/community.routeros/issues/6">see issue for details</a>).</p></li>
<li><p>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>ansible.netcommon.network_cli connection plugin</span></a> uses <a class="reference external" href="https://pypi.org/project/paramiko/">paramiko</a> by default to connect to devices with SSH. You can set its <code class="ansible-option docutils literal notranslate"><strong><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-parameter-ssh-type" title="(in Ansible vdevel)"><span><span class="pre">ssh_type</span></span></a></strong></code> option to <code class="ansible-value docutils literal notranslate"><span class="pre">libssh</span></code> to use <a class="reference external" href="https://pypi.org/project/ansible-pylibssh/">ansible-pylibssh</a> instead, which offers Python bindings to libssh. See its documentation for details.</p></li>
<li><p>User is <strong>not allowed</strong> to login via SSH by password to modern Mikrotik if SSH key for the user is added!</p></li>
</ol>
</section>
<section id="setting-up-an-inventory">
<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>
<span class="k">[routers:vars]</span>
<span class="na">ansible_connection</span><span class="o">=</span><span class="s">ansible.netcommon.network_cli</span>
<span class="na">ansible_network_os</span><span class="o">=</span><span class="s">community.routeros.routeros</span>
<span class="na">ansible_user</span><span class="o">=</span><span class="s">admin</span>
<span class="na">ansible_ssh_pass</span><span class="o">=</span><span class="s">test1234</span>
</pre></div>
</div>
<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>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="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>
<span class="w"> </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">routers</span>
<span class="w"> </span><span class="nt">gather_facts</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
<span class="w"> </span><span class="nt">tasks</span><span class="p">:</span>
<span class="w"> </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">Gather system resources</span>
<span class="w"> </span><span class="nt">community.routeros.command</span><span class="p">:</span>
<span class="w"> </span><span class="nt">commands</span><span class="p">:</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/system resource print</span>
<span class="w"> </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">system_resource_print</span>
<span class="w"> </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">Show system resources</span>
<span class="w"> </span><span class="nt">debug</span><span class="p">:</span>
<span class="w"> </span><span class="nt">var</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">system_resource_print.stdout_lines</span>
<span class="w"> </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">Gather facts</span>
<span class="w"> </span><span class="nt">community.routeros.facts</span><span class="p">:</span>
<span class="w"> </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">Show a fact</span>
<span class="w"> </span><span class="nt">debug</span><span class="p">:</span>
<span class="w"> </span><span class="nt">msg</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;First</span><span class="nv"> </span><span class="s">IP</span><span class="nv"> </span><span class="s">address:</span><span class="nv"> </span><span class="cp">{{</span> <span class="nv">ansible_net_all_ipv4_addresses</span><span class="o">[</span><span class="m">0</span><span class="o">]</span> <span class="cp">}}</span><span class="s">&quot;</span>
</pre></div>
</div>
<p>This results in the following output:</p>
<div class="highlight-ansible-output notranslate"><div class="highlight"><pre><span></span><span class="k">PLAY</span> <span class="p">[</span><span class="l">RouterOS test with network_cli connection</span><span class="p">]</span> <span class="nv">*****************************************************************</span>
<span class="k">TASK</span> <span class="p">[</span><span class="l">Gather system resources</span><span class="p">]</span> <span class="nv">***********************************************************************************</span>
<span class="k">ok</span><span class="p">:</span> <span class="p">[</span><span class="nv">router</span><span class="p">]</span>
<span class="k">TASK</span> <span class="p">[</span><span class="l">Show system resources</span><span class="p">]</span> <span class="nv">*************************************************************************************</span>
<span class="k">ok</span><span class="p">:</span> <span class="p">[</span><span class="nv">router</span><span class="p">]</span> <span class="p">=&gt;</span> <span class="p">{</span>
<span class="nt">&quot;system_resource_print.stdout_lines&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">[</span>
<span class="s">&quot;uptime: 3d10h28m51s&quot;</span><span class="p">,</span>
<span class="s">&quot; version: 6.48.3 (stable)&quot;</span><span class="p">,</span>
<span class="s">&quot; build-time: May/25/2021 06:09:45&quot;</span><span class="p">,</span>
<span class="s">&quot; free-memory: 31.2MiB&quot;</span><span class="p">,</span>
<span class="s">&quot; total-memory: 64.0MiB&quot;</span><span class="p">,</span>
<span class="s">&quot; cpu: MIPS 24Kc V7.4&quot;</span><span class="p">,</span>
<span class="s">&quot; cpu-count: 1&quot;</span><span class="p">,</span>
<span class="s">&quot; cpu-frequency: 400MHz&quot;</span><span class="p">,</span>
<span class="s">&quot; cpu-load: 1%&quot;</span><span class="p">,</span>
<span class="s">&quot; free-hdd-space: 54.2MiB&quot;</span><span class="p">,</span>
<span class="s">&quot; total-hdd-space: 128.0MiB&quot;</span><span class="p">,</span>
<span class="s">&quot; write-sect-since-reboot: 927&quot;</span><span class="p">,</span>
<span class="s">&quot; write-sect-total: 51572981&quot;</span><span class="p">,</span>
<span class="s">&quot; bad-blocks: 1%&quot;</span><span class="p">,</span>
<span class="s">&quot; architecture-name: mipsbe&quot;</span><span class="p">,</span>
<span class="s">&quot; board-name: RB750GL&quot;</span><span class="p">,</span>
<span class="s">&quot; platform: MikroTik&quot;</span>
<span class="p">]</span>
<span class="p">]</span>
<span class="p">}</span>
<span class="k">TASK</span> <span class="p">[</span><span class="l">Gather facts</span><span class="p">]</span> <span class="nv">**********************************************************************************************</span>
<span class="k">ok</span><span class="p">:</span> <span class="p">[</span><span class="nv">router</span><span class="p">]</span>
<span class="k">TASK</span> <span class="p">[</span><span class="l">Show a fact</span><span class="p">]</span> <span class="nv">***********************************************************************************************</span>
<span class="k">ok</span><span class="p">:</span> <span class="p">[</span><span class="nv">router</span><span class="p">]</span> <span class="p">=&gt;</span> <span class="p">{</span>
<span class="nt">&quot;msg&quot;</span><span class="p">:</span> <span class="s">&quot;First IP address: 192.168.2.1&quot;</span>
<span class="p">}</span>
<span class="k">PLAY RECAP</span> <span class="nv">*******************************************************************************************************</span>
<span class="n">router</span> <span class="p">:</span> <span class="k">ok</span><span class="p">=</span><span class="mi">4</span> <span class="k">changed</span><span class="p">=</span><span class="mi">0</span> <span class="k">unreachable</span><span class="p">=</span><span class="mi">0</span> <span class="k">failed</span><span class="p">=</span><span class="mi">0</span> <span class="k">skipped</span><span class="p">=</span><span class="mi">0</span> <span class="k">rescued</span><span class="p">=</span><span class="mi">0</span> <span class="k">ignored</span><span class="p">=</span><span class="mi">0</span>
</pre></div>
</div>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="api-guide.html" class="btn btn-neutral float-left" title="How to connect to RouterOS devices with the RouterOS API" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="quoting.html" class="btn btn-neutral float-right" title="How to quote and unquote commands and arguments" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright Community.Routeros Contributors.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script><!-- extra footer elements for Ansible beyond RTD Sphinx Theme -->
</body>
</html>