From 7a6b5e4f3a7a021cfa75faa7bf833741dfc09cff Mon Sep 17 00:00:00 2001 From: omnom62 <75066712+omnom62@users.noreply.github.com> Date: Sat, 22 Aug 2026 01:36:21 +1000 Subject: T8989: wave3 user, bgp_global, bgp_address_family, facts, firewall_global * T8989: vyos_user module * T8989: Wave 3 vyos_user module with integration and unit tests * T8989: Wave 3 vyos_bgp_global module with integration and unit tests * T8989: Wave 3 vyos_bgp_address_family module with integration and unit tests * T8989: Add overridden integration tests for vyos_bgp_global and vyos_bgp_address_family * T8989: vyos_facts * T8989: Add vyos_facts integration and unit tests with fixtures * T8989: vyos_firewall_global module * T8989: vyos_firewall_global module with integration and unit tests * T8989: vyos_firewall_rules module * T8989: vyos_firewall_rules module with integration and unit tests * T8989: vyos_firewall_interfaces module * T8989: vyos_firewall_interfaces module * T8989: vyos_firewall_interfaces UAT & SIT * T8989: vyos_firewall_interfaces UAT & SIT --- docs/vyos.rest.vyos_user_module.rst | 393 ++++++++++++++++++++++++++++++++++++ 1 file changed, 393 insertions(+) create mode 100644 docs/vyos.rest.vyos_user_module.rst (limited to 'docs/vyos.rest.vyos_user_module.rst') diff --git a/docs/vyos.rest.vyos_user_module.rst b/docs/vyos.rest.vyos_user_module.rst new file mode 100644 index 0000000..1ad08f4 --- /dev/null +++ b/docs/vyos.rest.vyos_user_module.rst @@ -0,0 +1,393 @@ +.. _vyos.rest.vyos_user_module: + + +******************* +vyos.rest.vyos_user +******************* + +**Manage user accounts on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages local user accounts on VyOS devices via the REST API. +- Uses REST API (``connection=httpapi``) instead of CLI. +- Passwords are write-only. Once set, they cannot be read back in plaintext. +- Use ``update_password=on_create`` to avoid resetting passwords on every run. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ state + +
+ string +
+ 		+
    Choices: +
  • present ←
    • +
  • absent
    • +
  • gathered
    • +
+ 		+
present ensures users exist with the specified configuration.
+
absent removes specified users.
+
gathered returns current user configuration as structured data.
+
+
+ users + +
+ list + / elements=dictionary +
+ 		+ +
List of user definitions.
+
+
+ full_name + +
+ string +
+ 		+ +
Full name of the user.
+
+
+ name + +
+ string + / required +
+ 		+ +
Username.
+
+
+ password + +
+ string +
+ 		+ +
Plaintext password. Write-only — hashed on device immediately.
+
+
+ public_keys + +
+ list + / elements=dictionary +
+ 		+ +
SSH public keys for the user.
+
+
+ key + +
+ string + / required +
+ 		+ +
Base64-encoded public key.
+
+
+ name + +
+ string + / required +
+ 		+ +
Key identifier/name.
+
+
+ type + +
+ string + / required +
+ 		+
    Choices: +
  • ssh-dss
    • +
  • ssh-rsa
    • +
  • ecdsa-sha2-nistp256
    • +
  • ecdsa-sha2-nistp384
    • +
  • ecdsa-sha2-nistp521
    • +
  • ssh-ed25519
    • +
+ 		+
Key type.
+
+
+ update_password + +
+ string +
+ 		+
    Choices: +
  • always ←
    • +
  • on_create
    • +
+ 		+
Control when password is updated.
+
always updates the password on every run (default).
+
on_create only sets the password when the user is first created.
+
+
+ + +Notes +----- + +.. note:: + - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. + - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. + - The ``vyos`` user cannot be deleted as it is required for API access. + - Passwords are hashed immediately by VyOS and cannot be read back. + + + +Examples +-------- + +.. code-block:: yaml + + - name: Create user + vyos.rest.vyos_user: + users: + - name: alice + full_name: Alice Smith + password: securepassword + update_password: on_create + state: present + + - name: Add SSH public key + vyos.rest.vyos_user: + users: + - name: alice + public_keys: + - name: alice-laptop + type: ssh-rsa + key: AAAAB3NzaC1yc2EAAAADAQABAAAB... + state: present + + - name: Delete user + vyos.rest.vyos_user: + users: + - name: alice + state: absent + + - name: Gather all users + vyos.rest.vyos_user: + state: gathered + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ list +
+ 		when changed +
User configuration after this module ran.
+
+
+
+ before + +
+ list +
+ 		always +
User configuration before this module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
List of API command tuples sent to the device.
+
+
+
+ gathered + +
+ list +
+ 		when state is gathered +
Current user configuration as structured data.
+
+
+
+ response + +
+ dictionary +
+ 		when changes are applied +
Raw API response.
+
+
+
+ saved + +
+ boolean +
+ 		when changes are applied +
Whether the config was saved after changes.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) -- cgit v1.2.3