<linkrel="next"title="How to quote and unquote commands and arguments"href="quoting.html"/>
<linkrel="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>
<bodyclass="wy-body-for-nav"><!-- extra body elements for Ansible beyond RTD Sphinx Theme -->
<liclass="toctree-l2"><aclass="reference internal"href="#setting-up-an-inventory">Setting up an inventory</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="#connecting-to-the-device">Connecting to the device</a></li>
</ul>
</li>
<liclass="toctree-l1"><aclass="reference internal"href="quoting.html">How to quote and unquote commands and arguments</a></li>
</ul>
<ul>
<liclass="toctree-l1"><aclass="reference internal"href="../api_module.html">community.routeros.api module – Ansible module for RouterOS API</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../api_facts_module.html">community.routeros.api_facts module – Collect facts from remote devices running MikroTik RouterOS using the API</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../api_find_and_modify_module.html">community.routeros.api_find_and_modify module – Find and modify information using the API</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../api_info_module.html">community.routeros.api_info module – Retrieve information from API</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../api_modify_module.html">community.routeros.api_modify module – Modify data at paths with API</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../command_module.html">community.routeros.command module – Run commands on remote devices running MikroTik RouterOS</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../routeros_cliconf.html">community.routeros.routeros cliconf – Use routeros cliconf to run command on MikroTik RouterOS platform</a></li>
</ul>
<ul>
<liclass="toctree-l1"><aclass="reference internal"href="../join_filter.html">community.routeros.join filter – Join a list of arguments to a command</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../list_to_dict_filter.html">community.routeros.list_to_dict filter – Convert a list of arguments to a dictionary</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../quote_argument_filter.html">community.routeros.quote_argument filter – Quote an argument</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../quote_argument_value_filter.html">community.routeros.quote_argument_value filter – Quote an argument value</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="../split_filter.html">community.routeros.split filter – Split a command into arguments</a></li>
<spanid="ansible-collections-community-routeros-docsite-ssh-guide"></span><h1>How to connect to RouterOS devices with SSH<aclass="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>
<ulclass="simple">
<li><p>The <aclass="reference internal"href="../facts_module.html#ansible-collections-community-routeros-facts-module"><spanclass="std std-ref">community.routeros.facts module</span></a> gathers facts about a RouterOS device;</p></li>
<li><p>The <aclass="reference internal"href="../command_module.html#ansible-collections-community-routeros-command-module"><spanclass="std std-ref">community.routeros.command module</span></a> executes commands on a RouterOS device.</p></li>
</ul>
<p>The modules need the <aclass="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)"><spanclass="xref std std-ref">ansible.netcommon.network_cli connection plugin</span></a> for this.</p>
<sectionid="important-notes">
<h2>Important notes<aclass="headerlink"href="#important-notes"title="Permalink to this heading"></a></h2>
<olclass="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 (<aclass="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 <aclass="reference internal"href="../command_module.html#ansible-collections-community-routeros-command-module"><spanclass="std std-ref">community.routeros.command module</span></a> does not support nesting commands and expects every command to start with a forward slash (<codeclass="docutils literal notranslate"><spanclass="pre">/</span></code>). Running the following command will produce an error:</p>
<li><p>When using the <aclass="reference internal"href="../command_module.html#ansible-collections-community-routeros-command-module"><spanclass="std std-ref">community.routeros.command module</span></a> module, make sure to not specify too long commands. Alternatively, add something like <codeclass="docutils literal notranslate"><spanclass="pre">+cet512w</span></code> to the username (replace <codeclass="docutils literal notranslate"><spanclass="pre">admin</span></code> with <codeclass="docutils literal notranslate"><spanclass="pre">admin+cet512w</span></code>) to tell RouterOS to not wrap before 512 characters in a line (<aclass="reference external"href="https://github.com/ansible-collections/community.routeros/issues/6">see issue for details</a>).</p></li>
<li><p>Finally, the <aclass="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)"><spanclass="xref std std-ref">ansible.netcommon.network_cli connection plugin</span></a> uses <aclass="reference external"href="https://pypi.org/project/paramiko/">paramiko</a> by default to connect to devices with SSH. You can set its <codeclass="ansible-option docutils literal notranslate"><strong><codeclass="docutils literal notranslate"><spanclass="pre">ssh_type`</span></code></strong></code> option to <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">libssh</span></code> to use <aclass="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>
<p>This tells Ansible that you have a RouterOS device called <codeclass="docutils literal notranslate"><spanclass="pre">router</span></code> with IP <codeclass="docutils literal notranslate"><spanclass="pre">192.168.2.1</span></code>. Ansible should use the <aclass="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)"><spanclass="xref std std-ref">ansible.netcommon.network_cli connection plugin</span></a> together with the the <aclass="reference internal"href="../routeros_cliconf.html#ansible-collections-community-routeros-routeros-cliconf"><spanclass="std std-ref">community.routeros.routeros cliconf plugin</span></a>. The credentials are stored as <codeclass="docutils literal notranslate"><spanclass="pre">ansible_user</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">ansible_ssh_pass</span></code> in the inventory.</p>
</section>
<sectionid="connecting-to-the-device">
<h2>Connecting to the device<aclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">/system</span><spanclass="pre">resource</span><spanclass="pre">print</span></code> on the device</p>
<spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="nt">name</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">RouterOS test with network_cli connection</span>
<divclass="highlight-ansible-output notranslate"><divclass="highlight"><pre><span></span><spanclass="k">PLAY</span><spanclass="p">[</span><spanclass="l">RouterOS test with network_cli connection</span><spanclass="p">]</span><spanclass="nv">*****************************************************************</span>
<spanclass="k">TASK</span><spanclass="p">[</span><spanclass="l">Gather system resources</span><spanclass="p">]</span><spanclass="nv">***********************************************************************************</span>
<spanclass="k">TASK</span><spanclass="p">[</span><spanclass="l">Show system resources</span><spanclass="p">]</span><spanclass="nv">*************************************************************************************</span>
<spanclass="k">TASK</span><spanclass="p">[</span><spanclass="l">Show a fact</span><spanclass="p">]</span><spanclass="nv">***********************************************************************************************</span>
<ahref="api-guide.html"class="btn btn-neutral float-left"title="How to connect to RouterOS devices with the RouterOS API"accesskey="p"rel="prev"><spanclass="fa fa-arrow-circle-left"aria-hidden="true"></span> Previous</a>
<ahref="quoting.html"class="btn btn-neutral float-right"title="How to quote and unquote commands and arguments"accesskey="n"rel="next">Next <spanclass="fa fa-arrow-circle-right"aria-hidden="true"></span></a>
