<linkrel="next"title="community.routeros.command module – Run commands on remote devices running MikroTik RouterOS"href="command_module.html"/>
<linkrel="prev"title="community.routeros.api_info module – Retrieve information from API"href="api_info_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"><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 current"><aclass="current reference internal"href="#">community.routeros.api_modify module – Modify data at paths with API</a><ul>
<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_modify module – Modify data at paths with API</li>
<liclass="wy-breadcrumbs-aside">
<!-- User defined GitHub URL -->
<ahref="https://github.com/ansible-collections/community.routeros/edit/main/plugins/modules/api_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_modify module – Modify data at paths with API<aclass="headerlink"href="#community-routeros-api-modify-module-modify-data-at-paths-with-api"title="Link to this heading"></a></h1>
<p>This module is part of the <aclass="reference external"href="https://galaxy.ansible.com/community/routeros">community.routeros collection</a> (version 2.9.0).</p>
You need further requirements to be able to use this module,
see <aclass="reference internal"href="#ansible-collections-community-routeros-api-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_modify</span></code>.</p>
</div>
<pclass="ansible-version-added">New in community.routeros 2.2.0</p>
<li><p>Allows to modify information for a path using the API.</p></li>
<li><p>Use the <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> module to modify one or multiple entries in a controlled way depending on some search conditions.</p></li>
<li><p>To make a backup of a path that can be restored with this module, use 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.</p></li>
<li><p>The module ignores dynamic and builtin entries.</p></li>
<li><p><strong>Note</strong> that this module is still heavily in development, and only supports <strong>some</strong> paths. If you want to support new paths, or think you found problems with existing paths, please first <aclass="reference external"href="https://github.com/ansible-collections/community.routeros/issues/">create an issue in the community.routeros Issue Tracker</a>.</p></li>
<spanid="ansible-collections-community-routeros-api-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-ca_path"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">path</span></p>
<p><spanclass="ansible-option-versionadded">added in community.routeros 1.2.0</span></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-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-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-modify-module-parameter-validate-certs"><spanclass="std std-ref"><spanclass="pre">validate_certs=true</span></span></a></code>.</p>
<aclass="ansibleOptionLink"href="#parameter-data"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">list</span> / <spanclass="ansible-option-elements">elements=dictionary</span> / <spanclass="ansible-option-required">required</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Data to ensure that is present for this path.</p>
<p>Fields not provided will not be modified.</p>
<p>If <codeclass="docutils literal notranslate"><spanclass="pre">.id</span></code> appears in an entry, it will be ignored.</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><spanclass="ansible-option-versionadded">added in community.routeros 2.1.0</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>Use the specified encoding when communicating with the RouterOS device.</p>
<aclass="ansibleOptionLink"href="#parameter-ensure_order"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">boolean</span></p>
<td><divclass="ansible-option-cell"><p>Whether to ensure the same order of the config as present in <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-modify-module-parameter-data"><spanclass="std std-ref"><spanclass="pre">data</span></span></a></strong></code>.</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><spanclass="ansible-option-versionadded">added in community.routeros 2.4.0</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-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-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-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-modify-module-parameter-ca-path"><spanclass="std std-ref"><spanclass="pre">ca_path</span></span></a></strong></code>.</p>
<aclass="ansibleOptionLink"href="#parameter-handle_absent_entries"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span></p>
<td><divclass="ansible-option-cell"><p>How to handle entries that are present in the current config, but not in <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-modify-module-parameter-data"><spanclass="std std-ref"><spanclass="pre">data</span></span></a></strong></code>.</p>
<aclass="ansibleOptionLink"href="#parameter-handle_entries_content"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span></p>
<td><divclass="ansible-option-cell"><p>For a single entry in <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-modify-module-parameter-data"><spanclass="std std-ref"><spanclass="pre">data</span></span></a></strong></code>, this describes how to handle fields that are not mentioned in that entry, but appear in the actual config.</p>
<p>If <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">ignore</span></code>, they are not modified.</p>
<p>If <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">remove</span></code>, they are removed. If at least one cannot be removed, the module will fail.</p>
<p>If <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">remove_as_much_as_possible</span></code>, all that can be removed will be removed. The ones that cannot be removed will be kept.</p>
<p>Note that <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">remove</span></code> and <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">remove_as_much_as_possible</span></code> do not apply to write-only fields.</p>
<aclass="ansibleOptionLink"href="#parameter-handle_read_only"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span></p>
<p><spanclass="ansible-option-versionadded">added in community.routeros 2.10.0</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>How to handle values passed in for read-only fields.</p>
<p>If <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">ignore</span></code>, they are not passed to the API.</p>
<p>If <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">validate</span></code>, the values are not passed for creation, and for updating they are compared to the value returned for the object. If they differ, the module fails.</p>
<p>If <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">error</span></code>, the module will fail if read-only fields are provided.</p>
<aclass="ansibleOptionLink"href="#parameter-handle_write_only"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">string</span></p>
<p><spanclass="ansible-option-versionadded">added in community.routeros 2.10.0</span></p>
</div></td>
<td><divclass="ansible-option-cell"><p>How to handle values passed in for write-only fields.</p>
<p>If <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">create_only</span></code>, they are passed on creation, and ignored for updating.</p>
<p>If <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">always_update</span></code>, they are always passed to the API. This means that if such a value is present, the module will always result in <codeclass="docutils literal notranslate"><spanclass="pre">changed</span></code> since there is no way to validate whether the value actually changed.</p>
<p>If <codeclass="ansible-value docutils literal notranslate"><spanclass="pre">error</span></code>, the module will fail if write-only fields are provided.</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 modification commands in <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-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-timeout"title="Permalink to this option"></a><pclass="ansible-option-type-line"><spanclass="ansible-option-type">integer</span></p>
<p><spanclass="ansible-option-versionadded">added in community.routeros 2.3.0</span></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-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><spanclass="ansible-option-versionadded">added in community.routeros 1.2.0</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-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-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-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>
<p><spanclass="ansible-option-versionadded">added in community.routeros 1.2.0</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-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-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-modify-module-parameter-ca-path"><spanclass="std std-ref"><spanclass="pre">ca_path</span></span></a></strong></code> option.</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>
<h2><aclass="toc-backref"href="#id5"role="doc-backlink">Notes</a><aclass="headerlink"href="#notes"title="Link to this heading"></a></h2>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<ulclass="simple">
<li><p>If write-only fields are present in the path, the module is <strong>not idempotent</strong> in a strict sense, since it is not able to verify the current value of these fields. The behavior the module should assume can be controlled with the <codeclass="ansible-option docutils literal notranslate"><strong><aclass="reference internal"href="#ansible-collections-community-routeros-api-modify-module-parameter-handle-write-only"><spanclass="std std-ref"><spanclass="pre">handle_write_only</span></span></a></strong></code> option.</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_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>
<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>
<spanclass="w"></span><spanclass="nt">comment</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">NAT to WAN</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-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>
<ahref="https://github.com/ansible-collections/community.routeros/issues/new?assignees=&labels=&template=bug_report.md"aria-role="button"target="_blank"rel="noopener external">Submit a bug report</a>
<ahref="https://github.com/ansible-collections/community.routeros/issues/new?assignees=&labels=&template=feature_request.md"aria-role="button"target="_blank"rel="noopener external">Request a feature</a>
