mirror.MikroTik/ansible-collections.community.routeros
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.routeros.git synced 2025-06-22 09:53:32 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 3
ansible-collections.communi.../branch/main/docsite/api-guide.html
felixfontein cda70580f8 deploy: 2333efcf0f
2023-06-22 18:46:32 +00:00

351 lines
No EOL
40 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
<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" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/css/ansible.css" type="text/css" />
<link rel="stylesheet" href="../_static/antsibull-minimal.css" type="text/css" />
<link rel="stylesheet" href="../_static/css/rtd-ethical-ads.css" type="text/css" />
<link rel="shortcut icon" href="../_static/images/Ansible-Mark-RGB_Black.png"/>
<!--[if lt IE 9]>
<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/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" href="../index.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/ansiblefest" target="_blank">AnsibleFest</a></li>
<li><a href="https://www.ansible.com/tower" target="_blank">Products</a></li>
<li><a href="https://www.ansible.com/community" target="_blank">Community</a></li>
<li><a href="https://www.ansible.com/webinars-training" target="_blank">Webinars & Training</a></li>
<li><a href="https://www.ansible.com/blog" target="_blank">Blog</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 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="Permalink 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>
<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 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>
<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>
<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="l l-Scalar l-Scalar-Plain">group/community.routeros.api</span>
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">hostname</span><span class="p p-Indicator">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.168.1.1</span>
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">password</span><span class="p p-Indicator">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">admin</span>
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">username</span><span class="p p-Indicator">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">test1234</span>
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain"># The following options configure TLS/SSL.</span>
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain"># Depending on your setup, these options need different values</span><span class="p p-Indicator">:</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&quot;</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="Permalink to this heading"></a></h2>
<p>It is recommended to always use <code class="ansible-option-value docutils literal notranslate"><span class="pre">tls=true</span></code> when connecting with the API, even if you are only connecting to the device through a trusted network. The following options control how TLS/SSL is used:</p>
<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 commerically trusted CA certificate to sign your device’s certificate, or have not included your CA certificate in Python’s truststore, you need to point this option to the CA certificate.</p>
</dd>
</dl>
<p>We recommend to create a CA certificate that is used to sign the certificates for your RouterOS devices, and have the certificates include the correct hostname(s), including the IP of the device. That way, you can fully enable TLS and be sure that you always talk to the correct device.</p>
<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>
<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>
<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>
<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="../index.html" class="btn btn-neutral float-left" title="Community.Routeros" 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>
Reference in a new issue View git blame Copy permalink