deploy: cf6c79e1b3

branch/main/api_info_module.html

@@ -287,13 +287,27 @@ see <a class="reference internal" href="#ansible-collections-community-routeros-
 </div></td>
 </tr>
 <tr class="row-even"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="parameter-include_read_only"></div><p class="ansible-option-title" id="ansible-collections-community-routeros-api-info-module-parameter-include-read-only"><strong>include_read_only</strong></p>
+<a class="ansibleOptionLink" href="#parameter-include_read_only" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
+<p><span class="ansible-option-versionadded">added in community.routeros 2.10.0</span></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>Whether to include read-only fields.</p>
+<p>By default, they are not returned.</p>
+<p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
+<ul class="simple">
+<li><p><code class="ansible-option-default-bold docutils literal notranslate"><span class="pre">false</span></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
+<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">true</span></code></p></li>
+</ul>
+</div></td>
+</tr>
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-password"></div><p class="ansible-option-title" id="ansible-collections-community-routeros-api-info-module-parameter-password"><strong>password</strong></p>
 <a class="ansibleOptionLink" href="#parameter-password" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span> / <span class="ansible-option-required">required</span></p>
 </div></td>
 <td><div class="ansible-option-cell"><p>RouterOS user password.</p>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-path"></div><p class="ansible-option-title" id="ansible-collections-community-routeros-api-info-module-parameter-path"><strong>path</strong></p>
 <a class="ansibleOptionLink" href="#parameter-path" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span> / <span class="ansible-option-required">required</span></p>
 </div></td>
@@ -458,7 +472,7 @@ see <a class="reference internal" href="#ansible-collections-community-routeros-
 </ul>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-port"></div><p class="ansible-option-title" id="ansible-collections-community-routeros-api-info-module-parameter-port"><strong>port</strong></p>
 <a class="ansibleOptionLink" href="#parameter-port" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">integer</span></p>
 </div></td>
@@ -466,7 +480,7 @@ see <a class="reference internal" href="#ansible-collections-community-routeros-
 <p>Defaults are <code class="ansible-value docutils literal notranslate"><span class="pre">8728</span></code> for the HTTP API, and <code class="ansible-value docutils literal notranslate"><span class="pre">8729</span></code> for the HTTPS API.</p>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-timeout"></div><p class="ansible-option-title" id="ansible-collections-community-routeros-api-info-module-parameter-timeout"><strong>timeout</strong></p>
 <a class="ansibleOptionLink" href="#parameter-timeout" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">integer</span></p>
 <p><span class="ansible-option-versionadded">added in community.routeros 2.3.0</span></p>
@@ -475,7 +489,7 @@ see <a class="reference internal" href="#ansible-collections-community-routeros-
 <p class="ansible-option-line"><span class="ansible-option-default-bold">Default:</span> <code class="ansible-option-default docutils literal notranslate"><span class="pre">10</span></code></p>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-tls"></div>
 <div class="ansibleOptionAnchor" id="parameter-ssl"></div><p class="ansible-option-title" id="ansible-collections-community-routeros-api-info-module-parameter-tls"><span id="ansible-collections-community-routeros-api-info-module-parameter-ssl"></span><strong>tls</strong></p>
 <a class="ansibleOptionLink" href="#parameter-tls" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-aliases">aliases: ssl</span></p>
@@ -489,7 +503,7 @@ see <a class="reference internal" href="#ansible-collections-community-routeros-
 </ul>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-unfiltered"></div><p class="ansible-option-title" id="ansible-collections-community-routeros-api-info-module-parameter-unfiltered"><strong>unfiltered</strong></p>
 <a class="ansibleOptionLink" href="#parameter-unfiltered" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
 </div></td>
@@ -502,14 +516,14 @@ see <a class="reference internal" href="#ansible-collections-community-routeros-
 </ul>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-username"></div><p class="ansible-option-title" id="ansible-collections-community-routeros-api-info-module-parameter-username"><strong>username</strong></p>
 <a class="ansibleOptionLink" href="#parameter-username" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span> / <span class="ansible-option-required">required</span></p>
 </div></td>
 <td><div class="ansible-option-cell"><p>RouterOS login user.</p>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-validate_cert_hostname"></div><p class="ansible-option-title" id="ansible-collections-community-routeros-api-info-module-parameter-validate-cert-hostname"><strong>validate_cert_hostname</strong></p>
 <a class="ansibleOptionLink" href="#parameter-validate_cert_hostname" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
 <p><span class="ansible-option-versionadded">added in community.routeros 1.2.0</span></p>
@@ -523,7 +537,7 @@ see <a class="reference internal" href="#ansible-collections-community-routeros-
 </ul>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-validate_certs"></div><p class="ansible-option-title" id="ansible-collections-community-routeros-api-info-module-parameter-validate-certs"><strong>validate_certs</strong></p>
 <a class="ansibleOptionLink" href="#parameter-validate_certs" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
 <p><span class="ansible-option-versionadded">added in community.routeros 1.2.0</span></p>

branch/main/api_modify_module.html

@@ -89,6 +89,7 @@
 <li class="toctree-l2"><a class="reference internal" href="#requirements">Requirements</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#parameters">Parameters</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#attributes">Attributes</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#notes">Notes</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#see-also">See Also</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#examples">Examples</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#return-values">Return Values</a><ul>
@@ -157,9 +158,10 @@ see <a class="reference internal" href="#ansible-collections-community-routeros-
 <li><p><a class="reference internal" href="#requirements" id="id2">Requirements</a></p></li>
 <li><p><a class="reference internal" href="#parameters" id="id3">Parameters</a></p></li>
 <li><p><a class="reference internal" href="#attributes" id="id4">Attributes</a></p></li>
-<li><p><a class="reference internal" href="#see-also" id="id5">See Also</a></p></li>
+<li><p><a class="reference internal" href="#notes" id="id5">Notes</a></p></li>
-<li><p><a class="reference internal" href="#examples" id="id6">Examples</a></p></li>
+<li><p><a class="reference internal" href="#see-also" id="id6">See Also</a></p></li>
-<li><p><a class="reference internal" href="#return-values" id="id7">Return Values</a></p></li>
+<li><p><a class="reference internal" href="#examples" id="id7">Examples</a></p></li>
+<li><p><a class="reference internal" href="#return-values" id="id8">Return Values</a></p></li>
 </ul>
 </nav>
 <section id="synopsis">
@@ -268,6 +270,7 @@ see <a class="reference internal" href="#ansible-collections-community-routeros-
 <p>If <code class="ansible-value docutils literal notranslate"><span class="pre">ignore</span></code>, they are not modified.</p>
 <p>If <code class="ansible-value docutils literal notranslate"><span class="pre">remove</span></code>, they are removed. If at least one cannot be removed, the module will fail.</p>
 <p>If <code class="ansible-value docutils literal notranslate"><span class="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 <code class="ansible-value docutils literal notranslate"><span class="pre">remove</span></code> and <code class="ansible-value docutils literal notranslate"><span class="pre">remove_as_much_as_possible</span></code> do not apply to write-only fields.</p>
 <p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
 <ul class="simple">
 <li><p><code class="ansible-option-default-bold docutils literal notranslate"><span class="pre">&quot;ignore&quot;</span></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
@@ -277,6 +280,40 @@ see <a class="reference internal" href="#ansible-collections-community-routeros-
 </div></td>
 </tr>
 <tr class="row-odd"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="parameter-handle_read_only"></div><p class="ansible-option-title" id="ansible-collections-community-routeros-api-modify-module-parameter-handle-read-only"><strong>handle_read_only</strong></p>
+<a class="ansibleOptionLink" href="#parameter-handle_read_only" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
+<p><span class="ansible-option-versionadded">added in community.routeros 2.10.0</span></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>How to handle values passed in for read-only fields.</p>
+<p>If <code class="ansible-value docutils literal notranslate"><span class="pre">ignore</span></code>, they are not passed to the API.</p>
+<p>If <code class="ansible-value docutils literal notranslate"><span class="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 <code class="ansible-value docutils literal notranslate"><span class="pre">error</span></code>, the module will fail if read-only fields are provided.</p>
+<p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
+<ul class="simple">
+<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">&quot;ignore&quot;</span></code></p></li>
+<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">&quot;validate&quot;</span></code></p></li>
+<li><p><code class="ansible-option-default-bold docutils literal notranslate"><span class="pre">&quot;error&quot;</span></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
+</ul>
+</div></td>
+</tr>
+<tr class="row-even"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="parameter-handle_write_only"></div><p class="ansible-option-title" id="ansible-collections-community-routeros-api-modify-module-parameter-handle-write-only"><strong>handle_write_only</strong></p>
+<a class="ansibleOptionLink" href="#parameter-handle_write_only" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
+<p><span class="ansible-option-versionadded">added in community.routeros 2.10.0</span></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>How to handle values passed in for write-only fields.</p>
+<p>If <code class="ansible-value docutils literal notranslate"><span class="pre">create_only</span></code>, they are passed on creation, and ignored for updating.</p>
+<p>If <code class="ansible-value docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">changed</span></code> since there is no way to validate whether the value actually changed.</p>
+<p>If <code class="ansible-value docutils literal notranslate"><span class="pre">error</span></code>, the module will fail if write-only fields are provided.</p>
+<p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
+<ul class="simple">
+<li><p><code class="ansible-option-default-bold docutils literal notranslate"><span class="pre">&quot;create_only&quot;</span></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
+<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">&quot;always_update&quot;</span></code></p></li>
+<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">&quot;error&quot;</span></code></p></li>
+</ul>
+</div></td>
+</tr>
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-hostname"></div><p class="ansible-option-title" id="ansible-collections-community-routeros-api-modify-module-parameter-hostname"><strong>hostname</strong></p>
 <a class="ansibleOptionLink" href="#parameter-hostname" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span> / <span class="ansible-option-required">required</span></p>
 </div></td>
@@ -570,8 +607,17 @@ see <a class="reference internal" href="#ansible-collections-community-routeros-
 </tbody>
 </table>
 </section>
+<section id="notes">
+<h2><a class="toc-backref" href="#id5" role="doc-backlink">Notes</a><a class="headerlink" href="#notes" title="Link to this heading"></a></h2>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<ul class="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 <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-routeros-api-modify-module-parameter-handle-write-only"><span class="std std-ref"><span class="pre">handle_write_only</span></span></a></strong></code> option.</p></li>
+</ul>
+</div>
+</section>
 <section id="see-also">
-<h2><a class="toc-backref" href="#id5" role="doc-backlink">See Also</a><a class="headerlink" href="#see-also" title="Link to this heading"></a></h2>
+<h2><a class="toc-backref" href="#id6" role="doc-backlink">See Also</a><a class="headerlink" href="#see-also" title="Link to this heading"></a></h2>
 <div class="admonition seealso">
 <p class="admonition-title">See also</p>
 <dl class="simple">
@@ -589,7 +635,7 @@ see <a class="reference internal" href="#ansible-collections-community-routeros-
 </div>
 </section>
 <section id="examples">
-<h2><a class="toc-backref" href="#id6" role="doc-backlink">Examples</a><a class="headerlink" href="#examples" title="Link to this heading"></a></h2>
+<h2><a class="toc-backref" href="#id7" role="doc-backlink">Examples</a><a class="headerlink" href="#examples" title="Link to this heading"></a></h2>
 <div class="highlight-yaml+jinja notranslate"><div class="highlight"><pre><span></span><span class="nn">---</span>
 <span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Setup DHCP server networks</span>
 <span class="w">  </span><span class="c1"># Ensures that we have exactly two DHCP server networks (in the specified order)</span>
@@ -631,7 +677,7 @@ see <a class="reference internal" href="#ansible-collections-community-routeros-
 </div>
 </section>
 <section id="return-values">
-<h2><a class="toc-backref" href="#id7" role="doc-backlink">Return Values</a><a class="headerlink" href="#return-values" title="Link to this heading"></a></h2>
+<h2><a class="toc-backref" href="#id8" role="doc-backlink">Return Values</a><a class="headerlink" href="#return-values" title="Link to this heading"></a></h2>
 <p>Common return values are documented <a class="reference external" href="https://docs.ansible.com/ansible/devel/reference_appendices/common_return_values.html#common-return-values" title="(in Ansible vdevel)"><span class="xref std std-ref">here</span></a>, the following are the fields unique to this module:</p>
 <table class="ansible-option-table docutils align-default" style="width: 100%">
 <thead>