<linkrel="next"title="community.routeros.api_facts module – Collect facts from remote devices running MikroTik RouterOS using the API"href="api_facts_module.html"/>
<linkrel="prev"title="How to quote and unquote commands and arguments"href="docsite/quoting.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-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>
</ul>
<!-- extra nav elements for Ansible beyond RTD Sphinx Theme -->
<liclass="breadcrumb-item active">community.routeros.api module – Ansible module for RouterOS API</li>
<liclass="wy-breadcrumbs-aside">
<!-- User defined GitHub URL -->
<ahref="https://github.com/ansible-collections/community.routeros/edit/main/plugins/modules/api.py?description=%23%23%23%23%23%20SUMMARY%0A%3C!—%20Your%20description%20here%20–%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr"class="fa fa-github"> Edit on GitHub</a>
<h1>community.routeros.api module – Ansible module for RouterOS API<aclass="headerlink"href="#community-routeros-api-module-ansible-module-for-routeros-api"title="Link to this heading"></a></h1>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>This module is part of the <aclass="reference external"href="https://galaxy.ansible.com/ui/repo/published/community/routeros/">community.routeros collection</a> (version 2.20.0).</p>
<p>It is not included in <codeclass="docutils literal notranslate"><spanclass="pre">ansible-core</span></code>.
To check whether it is installed, run <codeclass="code docutils literal notranslate"><spanclass="pre">ansible-galaxy</span><spanclass="pre">collection</span><spanclass="pre">list</span></code>.</p>
You need further requirements to be able to use this module,
see <aclass="reference internal"href="#ansible-collections-community-routeros-api-module-requirements"><spanclass="std std-ref">Requirements</span></a> for details.</p>
<p>To use it in a playbook, specify: <codeclass="code docutils literal notranslate"><spanclass="pre">community.routeros.api</span></code>.</p>
<h2><aclass="toc-backref"href="#id1"role="doc-backlink">Synopsis</a><aclass="headerlink"href="#synopsis"title="Link to this heading"></a></h2>
<ulclass="simple">
<li><p>Ansible module for RouterOS API with the Python <codeclass="docutils literal notranslate"><spanclass="pre">librouteros</span></code> library.</p></li>
<li><p>This module can add, remove, update, query and execute arbitrary command in RouterOS via API.</p></li>
</ul>
</section>
<sectionid="requirements">
<spanid="ansible-collections-community-routeros-api-module-requirements"></span><h2><aclass="toc-backref"href="#id2"role="doc-backlink">Requirements</a><aclass="headerlink"href="#requirements"title="Link to this heading"></a></h2>
<p>The below requirements are needed on the host that executes this module.</p>
<aclass="ansibleOptionLink"href="#parameter-add"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Will add selected arguments in selected path to RouterOS config.</p>
<aclass="ansibleOptionLink"href="#parameter-ca_path"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">path</span></p>
<p><emclass="ansible-option-versionadded">added in community.routeros 1.2.0</em></p>
</div></td>
<td><divclass="ansible-option-cell"><p>PEM formatted file that contains a CA certificate to be used for certificate validation.</p>
<p>See also <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-validate-cert-hostname"><spanclass="std std-ref"><spanclass="pre">validate_cert_hostname</span></span></a></strong></code>. Only used when <codeclass="ansible-option-value docutils literal notranslate"><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-tls"><spanclass="std std-ref"><spanclass="pre">tls=true</span></span></a></code> and <codeclass="ansible-option-value docutils literal notranslate"><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-validate-certs"><spanclass="std std-ref"><spanclass="pre">validate_certs=true</span></span></a></code>.</p>
<aclass="ansibleOptionLink"href="#parameter-cmd"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Execute any/arbitrary command in selected path, after the command we can add <codeclass="docutils literal notranslate"><spanclass="pre">.id</span></code>.</p>
<p>Example path <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">system</span><spanclass="pre">script</span></code> and cmd <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">run</span><spanclass="pre">.id=*03</span></code> is equivalent in RouterOS CLI <codeclass="docutils literal notranslate"><spanclass="pre">/system</span><spanclass="pre">script</span><spanclass="pre">run</span><spanclass="pre">number=0</span></code>.</p>
<p>Example path <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">ip</span><spanclass="pre">address</span></code> and cmd <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">print</span></code> is equivalent in RouterOS CLI <codeclass="docutils literal notranslate"><spanclass="pre">/ip</span><spanclass="pre">address</span><spanclass="pre">print</span></code>.</p>
<aclass="ansibleOptionLink"href="#parameter-encoding"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span></p>
<p><emclass="ansible-option-versionadded">added in community.routeros 2.1.0</em></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Use the specified encoding when communicating with the RouterOS device.</p>
<p>Default is <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">ASCII</span></code>. Note that <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">UTF-8</span></code> requires librouteros 3.2.1 or newer.</p>
<aclass="ansibleOptionLink"href="#parameter-extended_query"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">dictionary</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Extended query given path for selected query attributes from RouterOS API.</p>
<p>Extended query allow conjunctive input. If there is no matching entry, an empty list will be returned.</p>
<aclass="ansibleOptionLink"href="#parameter-extended_query/attributes"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">list</span> / <spanclass="ansible-option-elements">elements=string</span> / <spanclass="ansible-option-required">required</span></p>
</div></td>
<td><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-cell"><p>The list of attributes to return.</p>
<p>Every attribute used in a <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where"><spanclass="std std-ref"><spanclass="pre">extended_query.where[]</span></span></a></strong></code> clause need to be listed here.</p>
<aclass="ansibleOptionLink"href="#parameter-extended_query/where"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">list</span> / <spanclass="ansible-option-elements">elements=dictionary</span></p>
</div></td>
<td><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-cell"><p>Allows to restrict the objects returned.</p>
<p>The conditions here must all match. An <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-or"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].or</span></span></a></strong></code> condition needs at least one of its conditions to match.</p>
<aclass="ansibleOptionLink"href="#parameter-extended_query/where/attribute"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span></p>
</div></td>
<td><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-cell"><p>The attribute to match. Must be part of <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-attributes"><spanclass="std std-ref"><spanclass="pre">extended_query.attributes</span></span></a></strong></code>.</p>
<p>Either <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-or"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].or</span></span></a></strong></code> or all of <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-attribute"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].attribute</span></span></a></strong></code>, <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-is"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].is</span></span></a></strong></code>, and <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-value"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].value</span></span></a></strong></code> have to be specified.</p>
<aclass="ansibleOptionLink"href="#parameter-extended_query/where/is"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span></p>
</div></td>
<td><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-cell"><p>The operator to use for matching.</p>
<p>For equality use <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">==</span></code> or <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">eq</span></code>. For less use <codeclass="ansible-value docutils literal notranslate"><spanclass="pre"><</span></code> or <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">less</span></code>. For more use <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">></span></code> or <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">more</span></code>.</p>
<p>Use <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">in</span></code> to check whether the value is part of a list. In that case, <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-value"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].value</span></span></a></strong></code> must be a list.</p>
<p>Either <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-or"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].or</span></span></a></strong></code> or all of <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-attribute"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].attribute</span></span></a></strong></code>, <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-is"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].is</span></span></a></strong></code>, and <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-value"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].value</span></span></a></strong></code> have to be specified.</p>
<aclass="ansibleOptionLink"href="#parameter-extended_query/where/or"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">list</span> / <spanclass="ansible-option-elements">elements=dictionary</span></p>
</div></td>
<td><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-cell"><p>A list of conditions so that at least one of them has to match.</p>
<p>Either <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-or"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].or</span></span></a></strong></code> or all of <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-attribute"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].attribute</span></span></a></strong></code>, <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-is"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].is</span></span></a></strong></code>, and <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-value"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].value</span></span></a></strong></code> have to be specified.</p>
<aclass="ansibleOptionLink"href="#parameter-extended_query/where/or/attribute"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span> / <spanclass="ansible-option-required">required</span></p>
</div></td>
<td><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-cell"><p>The attribute to match. Must be part of <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-attributes"><spanclass="std std-ref"><spanclass="pre">extended_query.attributes</span></span></a></strong></code>.</p>
<aclass="ansibleOptionLink"href="#parameter-extended_query/where/or/is"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span> / <spanclass="ansible-option-required">required</span></p>
</div></td>
<td><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-cell"><p>The operator to use for matching.</p>
<p>For equality use <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">==</span></code> or <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">eq</span></code>. For less use <codeclass="ansible-value docutils literal notranslate"><spanclass="pre"><</span></code> or <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">less</span></code>. For more use <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">></span></code> or <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">more</span></code>.</p>
<p>Use <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">in</span></code> to check whether the value is part of a list. In that case, <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-or-value"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].or[].value</span></span></a></strong></code> must be a list.</p>
<aclass="ansibleOptionLink"href="#parameter-extended_query/where/or/value"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">any</span> / <spanclass="ansible-option-required">required</span></p>
</div></td>
<td><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-cell"><p>The value to compare to. Must be a list for <codeclass="ansible-option-value docutils literal notranslate"><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-or-is"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].or[].is=in</span></span></a></code>.</p>
<aclass="ansibleOptionLink"href="#parameter-extended_query/where/value"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">any</span></p>
</div></td>
<td><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-indent-desc"></div><divclass="ansible-option-cell"><p>The value to compare to. Must be a list for <codeclass="ansible-option-value docutils literal notranslate"><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-is"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].is=in</span></span></a></code>.</p>
<p>Either <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-or"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].or</span></span></a></strong></code> or all of <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-attribute"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].attribute</span></span></a></strong></code>, <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-is"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].is</span></span></a></strong></code>, and <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-extended-query-where-value"><spanclass="std std-ref"><spanclass="pre">extended_query.where[].value</span></span></a></strong></code> have to be specified.</p>
<aclass="ansibleOptionLink"href="#parameter-force_no_cert"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">boolean</span></p>
<p><emclass="ansible-option-versionadded">added in community.routeros 2.4.0</em></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Set to <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">true</span></code> to connect without a certificate when <codeclass="ansible-option-value docutils literal notranslate"><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-tls"><spanclass="std std-ref"><spanclass="pre">tls=true</span></span></a></code>.</p>
<p>See also <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-validate-certs"><spanclass="std std-ref"><spanclass="pre">validate_certs</span></span></a></strong></code>.</p>
<p><strong>Note:</strong> this forces the use of anonymous Diffie-Hellman (ADH) ciphers. The protocol is susceptible to Man-in-the-Middle attacks, because the keys used in the exchange are not authenticated. Instead of simply connecting without a certificate to “make things work” have a look at <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-validate-certs"><spanclass="std std-ref"><spanclass="pre">validate_certs</span></span></a></strong></code> and <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-ca-path"><spanclass="std std-ref"><spanclass="pre">ca_path</span></span></a></strong></code>.</p>
<aclass="ansibleOptionLink"href="#parameter-hostname"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span> / <spanclass="ansible-option-required">required</span></p>
<aclass="ansibleOptionLink"href="#parameter-password"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span> / <spanclass="ansible-option-required">required</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>RouterOS user password.</p>
<aclass="ansibleOptionLink"href="#parameter-path"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span> / <spanclass="ansible-option-required">required</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Main path for all other arguments.</p>
<p>If other arguments are not set, api will return all items in selected path.</p>
<aclass="ansibleOptionLink"href="#parameter-port"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">integer</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>RouterOS api port. If <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-tls"><spanclass="std std-ref"><spanclass="pre">tls</span></span></a></strong></code> is set, port will apply to TLS/SSL connection.</p>
<p>Defaults are <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">8728</span></code> for the HTTP API, and <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">8729</span></code> for the HTTPS API.</p>
<aclass="ansibleOptionLink"href="#parameter-query"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Query given path for selected query attributes from RouterOS aip.</p>
<p>WHERE is key word which extend query. WHERE format is key operator value - with spaces.</p>
<p>WHERE valid operators are <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">==</span></code> or <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">eq</span></code>, <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">!=</span></code> or <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">not</span></code>, <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">></span></code> or <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">more</span></code>, <codeclass="ansible-value docutils literal notranslate"><spanclass="pre"><</span></code> or <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">less</span></code>.</p>
<p>Example path <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">ip</span><spanclass="pre">address</span></code> and query <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">.id</span><spanclass="pre">address</span></code> will return only <codeclass="docutils literal notranslate"><spanclass="pre">.id</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">address</span></code> for all items in <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">ip</span><spanclass="pre">address</span></code> path.</p>
<p>Example path <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">ip</span><spanclass="pre">address</span></code> and query <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">.id</span><spanclass="pre">address</span><spanclass="pre">WHERE</span><spanclass="pre">address</span><spanclass="pre">==</span><spanclass="pre">1.1.1.3/32</span></code>. will return only <codeclass="docutils literal notranslate"><spanclass="pre">.id</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">address</span></code> for items in <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">ip</span><spanclass="pre">address</span></code> path, where address is eq to 1.1.1.3/32.</p>
<p>Example path <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">interface</span></code> and query <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">mtu</span><spanclass="pre">name</span><spanclass="pre">WHERE</span><spanclass="pre">mut</span><spanclass="pre">></span><spanclass="pre">1400</span></code> will return only interfaces <codeclass="docutils literal notranslate"><spanclass="pre">mtu,name</span></code> where mtu is bigger than 1400.</p>
<p>Equivalent in RouterOS CLI <codeclass="docutils literal notranslate"><spanclass="pre">/interface</span><spanclass="pre">print</span><spanclass="pre">where</span><spanclass="pre">mtu</span><spanclass="pre">></span><spanclass="pre">1400</span></code>.</p>
<aclass="ansibleOptionLink"href="#parameter-remove"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Remove config/value from RouterOS by ‘.id’.</p>
<p>Example <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">*03</span></code> will remove config/value with <codeclass="docutils literal notranslate"><spanclass="pre">id=*03</span></code> in selected path.</p>
<p>Equivalent in RouterOS CLI <codeclass="docutils literal notranslate"><spanclass="pre">/ip</span><spanclass="pre">address</span><spanclass="pre">remove</span><spanclass="pre">numbers=1</span></code>.</p>
<p>Note <codeclass="docutils literal notranslate"><spanclass="pre">number</span></code> in RouterOS CLI is different from <codeclass="docutils literal notranslate"><spanclass="pre">.id</span></code>.</p>
<aclass="ansibleOptionLink"href="#parameter-timeout"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">integer</span></p>
<p><emclass="ansible-option-versionadded">added in community.routeros 2.3.0</em></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Timeout for the request.</p>
<aclass="ansibleOptionLink"href="#parameter-tls"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-aliases">aliases: ssl</span></p>
<aclass="ansibleOptionLink"href="#parameter-update"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Update config/value in RouterOS by ‘.id’ in selected path.</p>
<p>Example <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">.id=*03</span><spanclass="pre">address=1.1.1.3/32</span></code> and path <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">ip</span><spanclass="pre">address</span></code> will replace existing ip address with <codeclass="docutils literal notranslate"><spanclass="pre">.id=*03</span></code>.</p>
<p>Equivalent in RouterOS CLI <codeclass="docutils literal notranslate"><spanclass="pre">/ip</span><spanclass="pre">address</span><spanclass="pre">set</span><spanclass="pre">address=1.1.1.3/32</span><spanclass="pre">numbers=1</span></code>.</p>
<p>Note <codeclass="docutils literal notranslate"><spanclass="pre">number</span></code> in RouterOS CLI is different from <codeclass="docutils literal notranslate"><spanclass="pre">.id</span></code>.</p>
<aclass="ansibleOptionLink"href="#parameter-username"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span> / <spanclass="ansible-option-required">required</span></p>
<aclass="ansibleOptionLink"href="#parameter-validate_cert_hostname"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">boolean</span></p>
<p><emclass="ansible-option-versionadded">added in community.routeros 1.2.0</em></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Set to <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">true</span></code> to validate hostnames in certificates.</p>
<p>See also <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-validate-certs"><spanclass="std std-ref"><spanclass="pre">validate_certs</span></span></a></strong></code>. Only used when <codeclass="ansible-option-value docutils literal notranslate"><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-tls"><spanclass="std std-ref"><spanclass="pre">tls=true</span></span></a></code> and <codeclass="ansible-option-value docutils literal notranslate"><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-validate-certs"><spanclass="std std-ref"><spanclass="pre">validate_certs=true</span></span></a></code>.</p>
<aclass="ansibleOptionLink"href="#parameter-validate_certs"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">boolean</span></p>
<p><emclass="ansible-option-versionadded">added in community.routeros 1.2.0</em></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Set to <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">false</span></code> to skip validation of TLS certificates.</p>
<p>See also <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-validate-cert-hostname"><spanclass="std std-ref"><spanclass="pre">validate_cert_hostname</span></span></a></strong></code>. Only used when <codeclass="ansible-option-value docutils literal notranslate"><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-tls"><spanclass="std std-ref"><spanclass="pre">tls=true</span></span></a></code>.</p>
<p><strong>Note:</strong> instead of simply deactivating certificate validations to “make things work”, please consider creating your own CA certificate and using it to sign certificates used for your router. You can tell the module about your CA certificate with the <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-module-parameter-ca-path"><spanclass="std std-ref"><spanclass="pre">ca_path</span></span></a></strong></code> option.</p>
<p><emclass="ansible-option-versionadded">added in community.routeros 2.1.0</em></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Use <codeclass="docutils literal notranslate"><spanclass="pre">group/community.routeros.api</span></code> in <codeclass="docutils literal notranslate"><spanclass="pre">module_defaults</span></code> to set defaults for this module.</p>
<td><divclass="ansible-option-cell"><p>Can run in <codeclass="docutils literal notranslate"><spanclass="pre">check_mode</span></code> and return changed status prediction without modifying target.</p>
<td><divclass="ansible-option-cell"><p>Will return details on what has changed (or possibly needs changing in <codeclass="docutils literal notranslate"><spanclass="pre">check_mode</span></code>), when in diff mode.</p>
<li><p>Use the <aclass="reference internal"href="api_modify_module.html#ansible-collections-community-routeros-api-modify-module"><spanclass="std std-ref">community.routeros.api_modify</span></a> and <aclass="reference internal"href="api_find_and_modify_module.html#ansible-collections-community-routeros-api-find-and-modify-module"><spanclass="std std-ref">community.routeros.api_find_and_modify</span></a> modules for more specific modifications, and the <aclass="reference internal"href="api_info_module.html#ansible-collections-community-routeros-api-info-module"><spanclass="std std-ref">community.routeros.api_info</span></a> module for a more controlled way of returning all entries for a path.</p></li>
</ul>
</div>
</section>
<sectionid="see-also">
<h2><aclass="toc-backref"href="#id6"role="doc-backlink">See Also</a><aclass="headerlink"href="#see-also"title="Link to this heading"></a></h2>
<divclass="admonition seealso">
<pclass="admonition-title">See also</p>
<dlclass="simple">
<dt><aclass="reference internal"href="docsite/quoting.html#ansible-collections-community-routeros-docsite-quoting"><spanclass="std std-ref">How to quote and unquote commands and arguments</span></a></dt><dd><p>How to quote and unquote commands and arguments</p>
</dd>
<dt><aclass="reference internal"href="api_facts_module.html#ansible-collections-community-routeros-api-facts-module"><spanclass="std std-ref">community.routeros.api_facts</span></a></dt><dd><p>Collect facts from remote devices running MikroTik RouterOS using the API.</p>
</dd>
<dt><aclass="reference internal"href="api_find_and_modify_module.html#ansible-collections-community-routeros-api-find-and-modify-module"><spanclass="std std-ref">community.routeros.api_find_and_modify</span></a></dt><dd><p>Find and modify information using the API.</p>
</dd>
<dt><aclass="reference internal"href="api_info_module.html#ansible-collections-community-routeros-api-info-module"><spanclass="std std-ref">community.routeros.api_info</span></a></dt><dd><p>Retrieve information from API.</p>
</dd>
<dt><aclass="reference internal"href="api_modify_module.html#ansible-collections-community-routeros-api-modify-module"><spanclass="std std-ref">community.routeros.api_modify</span></a></dt><dd><p>Modify data at paths with API.</p>
</dd>
<dt><aclass="reference internal"href="docsite/api-guide.html#ansible-collections-community-routeros-docsite-api-guide"><spanclass="std std-ref">How to connect to RouterOS devices with the RouterOS API</span></a></dt><dd><p>How to connect to RouterOS devices with the RouterOS API</p>
</dd>
</dl>
</div>
</section>
<sectionid="examples">
<h2><aclass="toc-backref"href="#id7"role="doc-backlink">Examples</a><aclass="headerlink"href="#examples"title="Link to this heading"></a></h2>
<divclass="highlight-yaml+jinja notranslate"><divclass="highlight"><pre><span></span><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">Get example - ip address print</span>
<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">Add example - ip address</span>
<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">Query example - ".id, address" in "ip address WHERE address == 192.168.255.10/24"</span>
<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">Extended query example - ".id,address,network" where address is not 192.168.255.10/24 or is 10.20.36.20/24</span>
<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">Update example - ether2 ip address with ".id = *14"</span>
<spanclass="w"></span><spanclass="no">comment=</span><spanclass="cp">{{</span><spanclass="s1">'Update 192.168.255.10/24 to 192.168.255.20/24 on ether2'</span><spanclass="o">|</span><spanclass="nf">community</span><spanclass="nv">.routeros.quote_argument_value</span><spanclass="cp">}}</span>
<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">Remove example - ether2 ip 192.168.255.20/24 with ".id = *14"</span>
<h2><aclass="toc-backref"href="#id8"role="doc-backlink">Return Values</a><aclass="headerlink"href="#return-values"title="Link to this heading"></a></h2>
<p>Common return values are documented <aclass="reference external"href="https://docs.ansible.com/ansible/devel/reference_appendices/common_return_values.html#common-return-values"title="(in Ansible vdevel)"><spanclass="xref std std-ref">here</span></a>, the following are the fields unique to this module:</p>
<aclass="ansibleOptionLink"href="#return-message"title="Permalink to this return value"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">list</span> / <spanclass="ansible-option-elements">elements=string</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>All outputs are in list with dictionary elements returned from RouterOS api.</p>
<li><span><aaria-role="button"class="ansible-link reference external"href="https://forum.ansible.com/tags/c/help/6/none/routeros"rel="noopener external"target="_blank">Ask for help (RouterOS)</a></span></li>
<li><span><aaria-role="button"class="ansible-link reference external"href="https://github.com/ansible-collections/community.routeros/issues/new?assignees=&labels=&template=bug_report.md"rel="noopener external"target="_blank">Submit a bug report</a></span></li>
<li><span><aaria-role="button"class="ansible-link reference external"href="https://github.com/ansible-collections/community.routeros/issues/new?assignees=&labels=&template=feature_request.md"rel="noopener external"target="_blank">Request a feature</a></span></li>
<ahref="docsite/quoting.html"class="btn btn-neutral float-left"title="How to quote and unquote commands and arguments"accesskey="p"rel="prev"><spanclass="fa fa-arrow-circle-left"aria-hidden="true"></span> Previous</a>
<ahref="api_facts_module.html"class="btn btn-neutral float-right"title="community.routeros.api_facts module – Collect facts from remote devices running MikroTik RouterOS using the API"accesskey="n"rel="next">Next <spanclass="fa fa-arrow-circle-right"aria-hidden="true"></span></a>
