<title>community.routeros.api_find_and_modify module – Find and modify information using the API — Community.Routeros Collection documentation</title>
<linkrel="next"title="community.routeros.api_info module – Retrieve information from API"href="api_info_module.html"/>
<linkrel="prev"title="community.routeros.api_facts module – Collect facts from remote devices running MikroTik RouterOS using the API"href="api_facts_module.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="docsite/api-guide.html">How to connect to RouterOS devices with the RouterOS API</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="docsite/ssh-guide.html">How to connect to RouterOS devices with SSH</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="docsite/quoting.html">How to quote and unquote commands and arguments</a></li>
</ul>
<ulclass="current">
<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 current"><aclass="current reference internal"href="#">community.routeros.api_find_and_modify module – Find and modify information using the API</a><ul>
<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>
<liclass="breadcrumb-item active">community.routeros.api_find_and_modify module – Find and modify information using the API</li>
<liclass="wy-breadcrumbs-aside">
<!-- User defined GitHub URL -->
<ahref="https://github.com/ansible-collections/community.routeros/edit/main/plugins/modules/api_find_and_modify.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_find_and_modify module – Find and modify information using the API<aclass="headerlink"href="#community-routeros-api-find-and-modify-module-find-and-modify-information-using-the-api"title="Link to this heading"></a></h1>
<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 3.1.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-find-and-modify-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_find_and_modify</span></code>.</p>
</div>
<pclass="ansible-version-added">New in community.routeros 2.1.0</p>
<li><p>Allows to find entries for a path by conditions and modify the values of these entries.</p></li>
<li><p>Use the <aclass="reference internal"href="#ansible-collections-community-routeros-api-find-and-modify-module"><spanclass="std std-ref">community.routeros.api_find_and_modify</span></a> module to set all entries of a path to specific values, or change multiple entries in different ways in one step.</p></li>
<spanid="ansible-collections-community-routeros-api-find-and-modify-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>
<aclass="ansibleOptionLink"href="#parameter-allow_no_matches"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">boolean</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Whether to allow that no match is found.</p>
<p>If not specified, this value is induced from whether <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-find-and-modify-module-parameter-require-matches-min"><spanclass="std std-ref"><spanclass="pre">require_matches_min</span></span></a></strong></code> is 0 or larger.</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>See also <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-find-and-modify-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-find-and-modify-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-find-and-modify-module-parameter-validate-certs"><spanclass="std std-ref"><spanclass="pre">validate_certs=true</span></span></a></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>
<aclass="ansibleOptionLink"href="#parameter-find"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">dictionary</span> / <spanclass="ansible-option-required">required</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Fields to search for.</p>
<p>The module will only consider entries in the given <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-find-and-modify-module-parameter-path"><spanclass="std std-ref"><spanclass="pre">path</span></span></a></strong></code> that match all fields provided here.</p>
<p>Use YAML <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">~</span></code>, or prepend keys with <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">!</span></code>, to specify an unset value.</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>
<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-find-and-modify-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-find-and-modify-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-find-and-modify-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-find-and-modify-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>Path to query.</p>
<p>An example value is <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">ip</span><spanclass="pre">address</span></code>. This is equivalent to running <codeclass="docutils literal notranslate"><spanclass="pre">/ip</span><spanclass="pre">address</span></code> in the RouterOS CLI.</p>
<aclass="ansibleOptionLink"href="#parameter-port"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">integer</span></p>
<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-find-and-modify-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-require_matches_max"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>Make sure that there are no more matches than this number.</p>
<p>If there are more matches, fail instead of modifying anything.</p>
<aclass="ansibleOptionLink"href="#parameter-require_matches_min"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>Make sure that there are no less matches than this number.</p>
<p>If there are less matches, fail instead of modifying anything.</p>
<aclass="ansibleOptionLink"href="#parameter-timeout"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">integer</span></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-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>
<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-find-and-modify-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-find-and-modify-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-find-and-modify-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>
<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-find-and-modify-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-find-and-modify-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-find-and-modify-module-parameter-ca-path"><spanclass="std std-ref"><spanclass="pre">ca_path</span></span></a></strong></code> option.</p>
<aclass="ansibleOptionLink"href="#parameter-values"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">dictionary</span> / <spanclass="ansible-option-required">required</span></p>
<td><divclass="ansible-option-cell"><p>On all entries matching the conditions in <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-find-and-modify-module-parameter-find"><spanclass="std std-ref"><spanclass="pre">find</span></span></a></strong></code>, set the keys of this option to the values specified here.</p>
<p>Use YAML <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">~</span></code>, or prepend keys with <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">!</span></code>, to specify to unset a value.</p>
<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>
<td><divclass="ansible-option-cell"><p>When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change.</p>
<p>This assumes that the system controlled/queried by the module has not changed in a relevant way.</p>
<li><p>If you want to change values based on their old values (like change all comments ‘foo’ to ‘bar’) and make sure that there are at least N such values, you can use <codeclass="ansible-option-value docutils literal notranslate"><aclass="reference internal"href="#ansible-collections-community-routeros-api-find-and-modify-module-parameter-require-matches-min"><spanclass="std std-ref"><spanclass="pre">require_matches_min=N</span></span></a></code> together with <codeclass="ansible-option-value docutils literal notranslate"><aclass="reference internal"href="#ansible-collections-community-routeros-api-find-and-modify-module-parameter-allow-no-matches"><spanclass="std std-ref"><spanclass="pre">allow_no_matches=true</span></span></a></code>. This will make the module fail if there are less than N such entries, but not if there is no match. The latter case is needed for idempotency of the task: once the values have been changed, there should be no further match.</p></li>
<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>
<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>
<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>
<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>
<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">Rename bridge from 'bridge' to 'my-bridge'</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">Change IP address to 192.168.1.1 for interface bridge - assuming there is only one</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-match_count"title="Permalink to this return value"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">integer</span></p>
<td><divclass="ansible-option-cell"><p>The number of entries that matched the criteria in <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-find-and-modify-module-parameter-find"><spanclass="std std-ref"><spanclass="pre">find</span></span></a></strong></code>.</p>
<aclass="ansibleOptionLink"href="#return-modify__count"title="Permalink to this return value"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">integer</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>The number of entries that were modified.</p>
<aclass="ansibleOptionLink"href="#return-new_data"title="Permalink to this return value"></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-cell"><p>A list of all elements for the current path after a change was made.</p>
<aclass="ansibleOptionLink"href="#return-old_data"title="Permalink to this return value"></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-cell"><p>A list of all elements for the current path before a change was made.</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>
