diff options
Diffstat (limited to 'docs/vyos.rest.vyos_config_module.rst')
| -rw-r--r-- | docs/vyos.rest.vyos_config_module.rst | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/docs/vyos.rest.vyos_config_module.rst b/docs/vyos.rest.vyos_config_module.rst new file mode 100644 index 0000000..9753ba3 --- /dev/null +++ b/docs/vyos.rest.vyos_config_module.rst @@ -0,0 +1,228 @@ +.. _vyos.rest.vyos_config_module: + + +********************* +vyos.rest.vyos_config +********************* + +**Manage VyOS configuration using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages VyOS device configuration via the REST API. +- Accepts configuration commands in CLI ``set``/``delete`` string format and applies them via the REST ``/configure`` endpoint. +- Uses REST API (``connection=httpapi``) instead of CLI. + + + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>lines</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>Ordered list of <code>set</code> or <code>delete</code> commands to apply.</div> + <div>Commands should be in standard VyOS CLI format, e.g. <code>set system host-name router1</code> or <code>delete protocols bgp</code>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>match</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>line</b> ←</div></li> + <li>none</li> + </ul> + </td> + <td> + <div>Controls how commands are matched against the running configuration.</div> + <div><code>line</code> checks each command against the running config and only applies commands that would change the configuration.</div> + <div><code>none</code> applies all commands without checking the running config.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>save</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Save the configuration to disk after applying changes.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>src</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>Path to a file containing <code>set</code>/<code>delete</code> commands, one per line.</div> + <div>Blank lines and lines starting with <code>#</code> are ignored.</div> + <div>Mutually exclusive with <code>lines</code>.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. + - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. + - Unlike the CLI collection's ``vyos_config``, this module does not support ``backup``, ``confirm``, or ``comment`` options as these are CLI-specific. + - Commands are parsed from CLI string format into REST API path arrays. + + + +Examples +-------- + +.. code-block:: yaml + + - name: Apply configuration lines + vyos.rest.vyos_config: + lines: + - set system host-name router1 + - set system domain-name example.com + - set interfaces ethernet eth0 description "WAN" + save: true + + - name: Delete configuration + vyos.rest.vyos_config: + lines: + - delete protocols bgp + save: true + + - name: Apply config from file + vyos.rest.vyos_config: + src: /tmp/vyos_config.txt + match: none + save: true + + - name: Always apply without matching + vyos.rest.vyos_config: + lines: + - set system host-name router1 + match: none + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>commands</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>always</td> + <td> + <div>List of commands applied to the device.</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>response</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>Raw API response from the device.</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>saved</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>when save is true and changes were made</td> + <td> + <div>Whether the configuration was saved to disk.</div> + <br/> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) |