mirror of
https://github.com/ansible-collections/community.routeros.git
synced 2025-06-22 09:53:32 +02:00
276 lines
No EOL
23 KiB
HTML
276 lines
No EOL
23 KiB
HTML
<!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 SSH — 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 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/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"><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="Permalink 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 class="xref std std-ref">ansible.netcommon.network_cli connection plugin</span></a> for this.</p>
|
||
<section id="important-notes">
|
||
<h2>Important notes<a class="headerlink" href="#important-notes" title="Permalink to this heading"></a></h2>
|
||
<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>Finally, the <a class="reference external" href="https://docs.ansible.com/ansible/devel/collections/ansible/netcommon/network_cli_connection.html#ansible-collections-ansible-netcommon-network-cli-connection" title="(in Ansible vdevel)"><span class="xref std std-ref">ansible.netcommon.network_cli connection plugin</span></a> 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><code class="docutils literal notranslate"><span class="pre">ssh_type`</span></code></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>
|
||
</ol>
|
||
</section>
|
||
<section id="setting-up-an-inventory">
|
||
<h2>Setting up an inventory<a class="headerlink" href="#setting-up-an-inventory" title="Permalink to this heading"></a></h2>
|
||
<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 class="xref std std-ref">ansible.netcommon.network_cli connection plugin</span></a> together with the the <a class="reference internal" href="../routeros_cliconf.html#ansible-collections-community-routeros-routeros-cliconf"><span class="std std-ref">community.routeros.routeros cliconf plugin</span></a>. The credentials are stored as <code class="docutils literal notranslate"><span class="pre">ansible_user</span></code> and <code class="docutils literal notranslate"><span class="pre">ansible_ssh_pass</span></code> in the inventory.</p>
|
||
</section>
|
||
<section id="connecting-to-the-device">
|
||
<h2>Connecting to the device<a class="headerlink" href="#connecting-to-the-device" title="Permalink to this heading"></a></h2>
|
||
<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">"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">"</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">=></span> <span class="p">{</span>
|
||
<span class="nt">"system_resource_print.stdout_lines"</span><span class="p">:</span> <span class="p">[</span>
|
||
<span class="p">[</span>
|
||
<span class="s">"uptime: 3d10h28m51s"</span><span class="p">,</span>
|
||
<span class="s">" version: 6.48.3 (stable)"</span><span class="p">,</span>
|
||
<span class="s">" build-time: May/25/2021 06:09:45"</span><span class="p">,</span>
|
||
<span class="s">" free-memory: 31.2MiB"</span><span class="p">,</span>
|
||
<span class="s">" total-memory: 64.0MiB"</span><span class="p">,</span>
|
||
<span class="s">" cpu: MIPS 24Kc V7.4"</span><span class="p">,</span>
|
||
<span class="s">" cpu-count: 1"</span><span class="p">,</span>
|
||
<span class="s">" cpu-frequency: 400MHz"</span><span class="p">,</span>
|
||
<span class="s">" cpu-load: 1%"</span><span class="p">,</span>
|
||
<span class="s">" free-hdd-space: 54.2MiB"</span><span class="p">,</span>
|
||
<span class="s">" total-hdd-space: 128.0MiB"</span><span class="p">,</span>
|
||
<span class="s">" write-sect-since-reboot: 927"</span><span class="p">,</span>
|
||
<span class="s">" write-sect-total: 51572981"</span><span class="p">,</span>
|
||
<span class="s">" bad-blocks: 1%"</span><span class="p">,</span>
|
||
<span class="s">" architecture-name: mipsbe"</span><span class="p">,</span>
|
||
<span class="s">" board-name: RB750GL"</span><span class="p">,</span>
|
||
<span class="s">" platform: MikroTik"</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">=></span> <span class="p">{</span>
|
||
<span class="nt">"msg"</span><span class="p">:</span> <span class="s">"First IP address: 192.168.2.1"</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>© 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> |