From b6b58bc747c4ea59371253c5541cde92b922c173 Mon Sep 17 00:00:00 2001 From: omnom62 <75066712+omnom62@users.noreply.github.com> Date: Wed, 19 Aug 2026 20:32:54 +1000 Subject: T6830: vyos_file module (support for file upload, management and templating) (#495) * T6830: vyos_file - support for copy, template, and upload * T6830: vyos_file - support for copy, template, and upload * T6830: vyos_file - support for copy, template, and upload * T6830: Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * T6830: vyos_file - AI comments fixed * T6830: vyos_file - AI comments fixed * T6830: vyos_file - AI comments fixed * T6830: Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * T6830: AI comments resolved * T6830: vyos_file - AI comments fixed * T6830: vyos_file - AI comments fixed * T6830: vyos_file - AI comments fixed * T6830: vyos_file - AI comments fixed * T6830: vyos_file - AI comments fixed --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/vyos.vyos.vyos_file_module.rst | 259 ++++++++++++++++++++++++++++++++++++ 1 file changed, 259 insertions(+) create mode 100644 docs/vyos.vyos.vyos_file_module.rst (limited to 'docs') diff --git a/docs/vyos.vyos.vyos_file_module.rst b/docs/vyos.vyos.vyos_file_module.rst new file mode 100644 index 00000000..a1bef8df --- /dev/null +++ b/docs/vyos.vyos.vyos_file_module.rst @@ -0,0 +1,259 @@ +.. _vyos.vyos.vyos_file_module: + + +******************* +vyos.vyos.vyos_file +******************* + +**Manage files, directories, and their ownership on VyOS devices** + + +Version added: 6.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Creates, updates, or removes a file or directory on a VyOS device, optionally pushing content from a local file (*src*) or inline text (*content*), and setting owner/group/mode via sudo chown/chmod. +- This module does not touch the configuration tree (config.boot). It manages arbitrary filesystem paths such as certificates or auth files under /config/auth/, which are not tracked by commit/save/rollback. +- All logic runs inside this module's main(), using the standard get_connection()/run_commands() pattern shared with vyos_command — there is no dedicated action plugin; this module uses the shared generic vyos action plugin like every other module in the collection. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ become + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes ←
    • +
+ 		+
Whether to prefix remote commands with sudo.
+
+
+ content + +
+ string +
+ 		+ +
Inline text content to write to dest. Marked no_log, since this module is commonly used to push credential material. Mutually exclusive with src.
+
Since content is a normal string-type module option, Ansible renders any Jinja expressions in it (e.g. {{ my_var }}) before this module ever runs, the same as any other option value — no special templating support is implemented by this module itself.
+
+
+ dest + +
+ path + / required +
+ 		+ +
Absolute path to the remote file or directory to manage.
+
+
+ group + +
+ string +
+ 		+ +
Name of the group that should own dest.
+
+
+ mode + +
+ string +
+ 		+ +
Permission bits for dest, as a string (e.g. '0600'). Compared against stat output after normalizing to 4 digits; '600' and '0600' are treated as equivalent.
+
+
+ owner + +
+ string +
+ 		+ +
Name of the user that should own dest.
+
+
+ src + +
+ path +
+ 		+ +
Path to a local file (on the Ansible controller) whose content should be pushed to dest. Transferred via a real SCP session over the connection's own persistent socket (the same mechanism ansible.netcommon.net_put uses), never placed inside a command string. Mutually exclusive with content.
+
File bytes are uploaded exactly as they exist on disk — Ansible does not render Jinja expressions inside the file's contents for src, only in the option values of the task itself (e.g. a templated path string). To push templated text, render it first with the template lookup and pass the result via content instead.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • present ←
    • +
  • absent
    • +
+ 		+
Whether the path should exist (present) or be removed (absent).
+
+
+ + +Notes +----- + +.. note:: + - This module works with connection ``ansible.netcommon.network_cli``. + - File state managed by this module is independent of VyOS's config revision system. A rollback to a previous config revision will not revert changes made by this module. + - Paths under */config/auth* are deliberately setgid ``vyattacfg`` by VyOS's own config-management convention (see vyos.dev T2713). If *mode* is given with a leading digit of ``0`` (e.g. ``'0750'``), this module compares only the rwx bits and will not report a diff for VyOS's own setgid bit. To manage the setgid/setuid/sticky bit explicitly, pass a non-zero leading digit (e.g. ``'2750'``). + + + +Examples +-------- + +.. code-block:: yaml + + - name: ensure the auth directory exists with correct ownership + vyos.vyos.vyos_file: + dest: /config/auth/office-vpn + owner: openvpn + group: openvpn + mode: '0750' + + - name: push a client certificate with correct ownership + vyos.vyos.vyos_file: + dest: /config/auth/office-vpn/client.pem + src: files/office-vpn-client.pem + owner: openvpn + group: openvpn + mode: '0600' + + - name: remove a stale cert + vyos.vyos.vyos_file: + dest: /config/auth/old-vpn/client.pem + state: absent + + - name: push templated LDAP auth config (content is rendered by Ansible before this module runs) + vyos.vyos.vyos_file: + dest: /config/auth/office-vpn/ldap-auth.config + content: "{{ lookup('template', 'ldap_auth.config.j2') }}" + owner: openvpn + group: openvpn + mode: '0640' + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + +
KeyReturnedDescription
+
+ diff_fields + +
+ list + / elements=string +
+ 		always +
Fields that differed between requested and actual state and were converged.
+
+
Sample:
+
['owner', 'mode', 'content']
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS maintainers and contributors (@vyos) -- cgit v1.2.3