community.openwrt.wg_peer module – Manage WireGuard/AmneziaWG peer UCI sections

Note

This module is part of the community.openwrt collection (version 1.11.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.openwrt.

To use it in a playbook, specify: community.openwrt.wg_peer.

New in community.openwrt 1.10.0

Synopsis

• Writes WireGuard/AmneziaWG peer UCI sections for an interface.

• Takes the peer’s resolved key material (public key, optional PSK, endpoint) from controller facts; the interface itself must already exist (see community.openwrt.wg_interface).

Note

This module has a corresponding action plugin.

Parameters

Parameter	Comments
peer_id_template string	Ucode template for the peer UCI section id. Rendered with these variables in scope: iface_name (peers[].iface), section (peers[].section) and proto (peers[].proto, then the interface section’s proto, then proto). Default: "{% if (section): %}peer_{{ iface_name }}_{{ section }}{% else %}peer_{{ iface_name }}{% endif %}"
peers list / elements=dictionary / required	List of peer configurations to write. Each suboption below sets the UCI option of the same name. When a suboption with no default is not set, that option is removed from an existing peer section. Other options of the section are left alone.
allowed_ips list / elements=string	List of allowed IPs/prefixes. Default: ["0.0.0.0/0", "::/0"]
description string	Peer description/label. Defaults to peers[].section when set, otherwise to peers[].iface.
endpoint_host string	Peer endpoint host. Empty to omit (spoke does not dial).
endpoint_port integer	Peer endpoint port.
iface string / required	Parent interface name.
persistent_keepalive integer	Peer persistent keepalive interval. The option is omitted when not set.
preshared_key string	Peer pre-shared key (optional). Never generated by this module; it is supplied by the caller (resolved/shared by community.openwrt.wg_interface). When not set, any pre-shared key already present in the peer section is removed.
proto string	Peer protocol; the peer section type becomes <proto>_<iface>. Defaults to the proto of the interface section, then to the module-wide proto, then to wireguard. community.openwrt.wg_interface resolves it the same way. When the protocol of an existing peer section changes, its type is changed in place. Choices: "wireguard" "amneziawg"
public_key string	Peer public key. Required when the peer state is present.
route_allowed_ips boolean	Whether to add routes for the peer’s allowed IPs (OpenWrt route_allowed_ips). Choices: false ← (default) true
section string	Peer section suffix, available as section in the peer_id_template template scope when deriving the peer section id.
state string	Whether the peer section should be present or absent. When absent, the peer section is removed. Defaults to the module-wide state when not set. Choices: "present" "absent"
proto string	Module-wide protocol, used for every peer whose own peers[].proto is not set and whose interface section has no proto either. wireguard when not set. Choices: "wireguard" "amneziawg"
state string	Module-wide state, used as the default for every peer whose own peers[].state is not set. An explicitly-set peers[].state overrides this for that peer. Choices: "present" ← (default) "absent"

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: full	Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.
platform	Platform: OpenWrt	Target platform for this module.

Notes

Note

• This module writes peer UCI sections only; it does not establish tunnels.

• Set the no_log task keyword on tasks passing peers[].preshared_key, to keep the pre-shared keys out of the output and logs.

• The peer section ID is rendered from peer_id_template and must match the ID used by community.openwrt.wg_interface when resolving pre-shared keys.

• Template options (peer_id_template) use ucode’s native template engine (Jinja-style {{ ... }} / {% ... %}).

See Also

See also

community.openwrt.wg_interface

Manage WireGuard/AmneziaWG identity keys, interface UCI sections and WAN ingress firewall rules.

Examples

# Hub: write peer sections for two spokes on the wg0 interface
- community.openwrt.wg_peer:
    peers:
      - iface: wg0
        section: spoke1
        public_key: "AFakeSpoke1PublicKey"
        preshared_key: "AFakeSpoke1Psk"
        endpoint_host: "spoke1.example.com"
        endpoint_port: 51820
        allowed_ips:
          - "10.8.0.2/32"
      - iface: wg0
        section: spoke2
        public_key: "AFakeSpoke2PublicKey"
        preshared_key: "AFakeSpoke2Psk"
        endpoint_host: "spoke2.example.com"
        endpoint_port: 51820
        allowed_ips:
          - "10.8.0.3/32"

# Two independent p2p links: one peer per link interface (no section)
- community.openwrt.wg_peer:
    peers:
      - iface: wg_l1
        public_key: "AFakeLink1PeerPublicKey"
        preshared_key: "AFakeLink1PeerPsk"
        endpoint_host: "link1-peer.example.com"
        endpoint_port: 51821
        allowed_ips:
          - "10.9.0.2/32"
      - iface: wg_l2
        public_key: "AFakeLink2PeerPublicKey"
        preshared_key: "AFakeLink2PeerPsk"
        endpoint_host: "link2-peer.example.com"
        endpoint_port: 51822
        allowed_ips:
          - "10.10.0.2/32"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
peers list / elements=string	Names of the (re)written peer sections. Returned: always
removed list / elements=string	Names of peer sections removed because their peers[].state, or state, was absent. Returned: always

Authors

• Vladimir Ermakov (@vooon)

Collection links

• Issue Tracker
• Repository (Sources)
• Report an issue
• Communication