vyos.vyos.vyos_nat module – NAT resource module

Note

This module is part of the vyos.vyos collection (version 6.2.0).

You might already have this collection installed if you are using the ansible package. 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 vyos.vyos.

To use it in a playbook, specify: vyos.vyos.vyos_nat.

New in vyos.vyos 6.0.0

Synopsis

• This module manages NAT configuration on devices running VyOS.

Aliases: nat

Parameters

Parameter	Comments
config dictionary	The desired configuration for the NAT resource represented as a dictionary.
nat dictionary	Configuration for NAT rules.
cgnat dictionary	Configuration for Carrier Grade NAT (CGNAT).
log_allocation boolean	Log CGNAT address allocations. Choices: false true
pool dictionary	Configuration for CGNAT pools.
external list / elements=dictionary	List of external NAT pools for CGNAT.
external_port_range string	Port range to use for NAT translations in this external pool.
name string / required	Name of the external NAT pool.
per_user_limit dictionary	Per-user limit configuration for the external pool.
port string	Maximum number of ports allocated per user.
range list / elements=dictionary	List of external IP address ranges in the pool.
seq string	Optional sequence number for this range entry.
value string / required	IP address, prefix, or range (e.g. 203.0.113.0/24 or 203.0.113.1-203.0.113.60).
internal list / elements=dictionary	List of internal NAT pools for CGNAT.
name string / required	Name of the internal NAT pool.
range list / elements=string	List of internal IP addresses or prefixes in the pool.
rule list / elements=dictionary	List of CGNAT rules.
id integer / required	Rule number for CGNAT.
source dictionary	Source pool configuration for CGNAT translation.
pool string	Source pool name to use for CGNAT translation.
translation dictionary	Translation pool configuration for CGNAT.
pool string	Translation pool name to use for CGNAT translation.
destination dictionary	Configuration for destination NAT rules.
rule list / elements=dictionary	List of destination NAT rules.
description string	User-friendly description of the destination NAT rule.
destination dictionary	Match criteria for destination NAT.
address string	IP address, subnet, or range to match.
address_group string	Address group name to match.
domain_group string	Domain group name to match.
fqdn string	Fully qualified domain name to match.
mac_group string	MAC address group name to match.
network_group string	Network group name to match.
port string	Port number or range to match.
port_group string	Port group name to match.
disable boolean	Disable this destination NAT rule. Choices: false true
exclude boolean	Exclude packets matching this rule from NAT. Choices: false true
id integer / required	Rule number for destination NAT.
inbound_interface dictionary	Match inbound interface.
group string	Interface group to match.
name string	Interface name to match.
load_balance dictionary	Load balancing configuration for this NAT rule.
backend list / elements=dictionary	List of backends to load-balance across. Weights should sum to 100.
ip string	IP address of the backend translation target.
weight integer	Relative weight (1-100) for this backend’s share of load-balanced traffic.
hash list / elements=string	Fields to hash on for load balancing. Mutually exclusive with translation.address. Choices: "source-address" "destination-address" "source-port" "destination-port" "random"
log boolean	Log packets hitting this rule. Choices: false true
packet_type string	Packet type to match.
protocol string	Protocol to NAT (default all).
translation dictionary	Translation configuration for destination NAT.
address string	IP address or prefix to translate destination to.
address_mapping string	Address mapping mode for translation. Choices: "random" "persistent"
port string	Port number or range to translate destination port to.
port_mapping string	Port mapping mode for translation. Choices: "random" "none"
redirect_port string	Redirect to local port number.
source dictionary	Configuration for source NAT rules.
rule list / elements=dictionary	List of source NAT rules.
description string	User-friendly description of the source NAT rule.
destination dictionary	Destination match criteria for source NAT.
address string	IP address, subnet, or range to match.
address_group string	Address group name to match.
domain_group string	Domain group name to match.
fqdn string	Fully qualified domain name to match.
mac_group string	MAC address group name to match.
network_group string	Network group name to match.
port string	Port number or range to match.
port_group string	Port group name to match.
disable boolean	Disable this source NAT rule. Choices: false true
exclude boolean	Exclude packets matching this rule from NAT. Choices: false true
id integer / required	Rule number for source NAT.
load_balance dictionary	Load balancing configuration for this NAT rule.
backend list / elements=dictionary	List of backends to load-balance across. Weights should sum to 100.
ip string	IP address of the backend translation target.
weight integer	Relative weight (1-100) for this backend’s share of load-balanced traffic.
hash list / elements=string	Fields to hash on for load balancing. Mutually exclusive with translation.address. Choices: "source-address" "destination-address" "source-port" "destination-port" "random"
log boolean	Log packets hitting this rule. Choices: false true
outbound_interface dictionary	Match outbound interface.
group string	Interface group to match.
name string	Interface name to match.
packet_type string	Packet type to match.
protocol string	Protocol to NAT (default all).
source dictionary	Source match criteria for source NAT.
address string	IP address, subnet, or range to match.
address_group string	Address group name to match.
domain_group string	Domain group name to match.
fqdn string	Fully qualified domain name to match.
mac_group string	MAC address group name to match.
network_group string	Network group name to match.
port string	Port number or range to match.
port_group string	Port group name to match.
translation dictionary	Translation configuration for source NAT.
address string	IP address or prefix to translate source to. Use masquerade to masquerade as the outbound interface address.
address_mapping string	Address mapping mode for translation. Choices: "random" "persistent"
port string	Port number or range to translate source port to.
port_mapping string	Port mapping mode for translation. Choices: "random" "none"
static dictionary	Configuration for static one-to-one NAT rules.
rule list / elements=dictionary	List of static NAT rules.
description string	User-friendly description of the static NAT rule.
destination dictionary	Match criteria for static NAT.
address string	IP address, subnet, or range to match.
id integer / required	Rule number for static NAT.
inbound_interface string	Inbound interface that this static NAT rule applies to.
log boolean	Log packets hitting this static NAT rule. Choices: false true
translation dictionary	Translation configuration for static NAT.
address string	IP address or prefix to translate to.
nat64 dictionary	Configuration for NAT64 (IPv6-to-IPv4) rules.
source dictionary	Configuration for NAT64 source rules.
rule list / elements=dictionary	List of NAT64 source rules.
description string	User-friendly description of the NAT64 source rule.
disable boolean	Disable this NAT64 source rule. Choices: false true
id integer / required	Rule number for NAT64 source rule (1-999999).
match dictionary	Match criteria for NAT64 source rule.
mark integer	Match on firewall mark value (1-2147483647).
source dictionary	IPv6 source prefix to match for NAT64 translation.
prefix string	IPv6 source prefix to match (h:h:h:h:h:h:h:h/x).
translation dictionary	Translation configuration for NAT64 source rule.
pool list / elements=dictionary	List of translation pools for NAT64.
address string	IPv4 address or prefix for translation pool.
description string	User-friendly description of the translation pool.
disable boolean	Disable this translation pool. Choices: false true
id integer / required	Pool number (1-999999).
port string	Port number or range for translation pool.
protocol string	Protocol for this translation pool entry. Choices: "icmp" "tcp" "udp"
nat66 dictionary	Configuration for NAT66 (IPv6-to-IPv6) rules.
destination dictionary	Configuration for NAT66 destination rules.
rule list / elements=dictionary	List of NAT66 destination rules.
description string	User-friendly description of the NAT66 destination rule.
destination dictionary	Match criteria for NAT66 destination rule.
address string	IPv6 address or prefix to match.
port string	Port number or range to match.
disable boolean	Disable this NAT66 destination rule. Choices: false true
exclude boolean	Exclude packets matching this rule from NAT66. Choices: false true
id integer / required	Rule number for NAT66 destination rule.
inbound_interface dictionary	Inbound interface to match for NAT66 destination rule.
name string	Interface name to match.
log boolean	Log packets hitting this NAT66 destination rule. Choices: false true
protocol string	Protocol to match.
source dictionary	Source match criteria for NAT66 destination rule.
address string	IPv6 source address or prefix to match.
port string	Source port number or range to match.
translation dictionary	Translation configuration for NAT66 destination rule.
address string	IPv6 address or prefix to translate destination to.
port string	Port number or range to translate destination port to.
source dictionary	Configuration for NAT66 source rules.
rule list / elements=dictionary	List of NAT66 source rules.
description string	User-friendly description of the NAT66 source rule.
destination dictionary	Destination match criteria for NAT66 source rule.
port string	Destination port number or range to match.
prefix string	IPv6 destination prefix to match (h:h:h:h:h:h:h:h/x).
disable boolean	Disable this NAT66 source rule. Choices: false true
exclude boolean	Exclude packets matching this rule from NAT66. Choices: false true
id integer / required	Rule number for NAT66 source rule.
log boolean	Log packets hitting this NAT66 source rule. Choices: false true
outbound_interface dictionary	Outbound interface to match for NAT66 source rule.
name string	Interface name to match.
protocol string	Protocol to match.
source dictionary	Source match criteria for NAT66 source rule.
port string	Source port number or range to match.
prefix string	IPv6 source prefix to match (h:h:h:h:h:h:h:h/x).
translation dictionary	Translation configuration for NAT66 source rule.
address string	IPv6 address or prefix to translate source to. Use masquerade to masquerade as the outbound interface address.
port string	Port number or range to translate source port to.
running_config string	This option is used only with state parsed. The value of this option should be the output received from the VyOS device by executing the command show configuration commands | match ‘nat’. The state parsed reads the configuration from show configuration commands | match 'nat' and transforms it into Ansible structured data as per the module argspec. The value is then returned in the parsed key within the result. The state replaced replaces only the provided configuration, while overridden removes any existing NAT configuration not specified in config.
state string	The state the configuration should be left in. Choices: "deleted" "merged" ← (default) "overridden" "replaced" "gathered" "rendered" "parsed"

Notes

Note

• Tested against VyOS 1.4.3 and 1.5.0.

• This module works with connection network_cli.

Examples

# Using merged - configure CGNAT
- name: Merge CGNAT configuration
  vyos.vyos.vyos_nat:
    config:
      nat:
        cgnat:
          log_allocation: true
          pool:
            external:
              - name: ext-pool-1
                external_port_range: "10000-20000"
                per_user_limit:
                  port: "200"
                range:
                  - value: 203.0.113.0/24
            internal:
              - name: int-pool-1
                range:
                  - 10.0.0.0/24
          rule:
            - id: 1
              source:
                pool: int-pool-1
              translation:
                pool: ext-pool-1
    state: merged

# Using merged - configure destination NAT
- name: Merge destination NAT rule
  vyos.vyos.vyos_nat:
    config:
      nat:
        destination:
          rule:
            - id: 100
              description: "Web server NAT"
              protocol: tcp
              log: true
              destination:
                address: 198.51.100.10
                port: "80"
              translation:
                address: 192.168.1.10
                port: "8080"
    state: merged

# Using merged - configure source NAT
- name: Merge source NAT rule
  vyos.vyos.vyos_nat:
    config:
      nat:
        source:
          rule:
            - id: 200
              description: "Outbound masquerade"
              protocol: tcp
              log: true
              outbound_interface:
                name: eth0
              translation:
                address: masquerade
    state: merged

# Using merged - configure static NAT
- name: Merge static NAT rule
  vyos.vyos.vyos_nat:
    config:
      nat:
        static:
          rule:
            - id: 300
              description: "Static mapping"
              inbound_interface: eth2
              destination:
                address: 198.51.100.20
              translation:
                address: 192.168.1.20
              log: true
    state: merged

# Using merged - configure NAT64
- name: Merge NAT64 source rule
  vyos.vyos.vyos_nat:
    config:
      nat64:
        source:
          rule:
            - id: 10
              description: "NAT64 example"
              source:
                prefix: 2001:db8::/96
              match:
                mark: 100
              translation:
                pool:
                  - id: 1
                    address: 192.168.100.10
                    port: "1-65535"
                    protocol: udp
    state: merged

# Using merged - configure NAT66
- name: Merge NAT66 destination rule
  vyos.vyos.vyos_nat:
    config:
      nat66:
        destination:
          rule:
            - id: 20
              description: "NAT66 DNAT"
              protocol: tcp
              inbound_interface:
                name: eth1
              destination:
                address: 2001:db8::1
              translation:
                address: 2001:db8:1::10
                port: "8443"
    state: merged

# Using replaced - replace specific NAT rules
- name: Replace destination NAT rule
  vyos.vyos.vyos_nat:
    config:
      nat:
        destination:
          rule:
            - id: 100
              description: "Replaced web server NAT"
              protocol: tcp
              destination:
                address: 198.51.100.10
                port: "443"
              translation:
                address: 192.168.1.10
                port: "8443"
    state: replaced

# Using overridden - override entire NAT configuration
- name: Override entire NAT configuration
  vyos.vyos.vyos_nat:
    config:
      nat:
        destination:
          rule:
            - id: 100
              description: "Only rule after override"
              protocol: tcp
              destination:
                address: 198.51.100.10
                port: "80"
              translation:
                address: 192.168.1.10
                port: "8080"
    state: overridden

# Using deleted - delete all NAT configuration
- name: Delete all NAT configuration
  vyos.vyos.vyos_nat:
    state: deleted

# Using deleted - delete specific NAT rules
- name: Delete specific NAT rules
  vyos.vyos.vyos_nat:
    config:
      nat:
        destination:
          rule:
            - id: 100
        source:
          rule:
            - id: 200
      nat64:
        source:
          rule:
            - id: 10
    state: deleted

# Using gathered
- name: Gather NAT configuration from device
  vyos.vyos.vyos_nat:
    state: gathered

# Using rendered
- name: Render NAT configuration offline
  vyos.vyos.vyos_nat:
    config:
      nat:
        destination:
          rule:
            - id: 100
              description: "Rendered rule"
              protocol: tcp
              destination:
                address: 198.51.100.10
                port: "80"
              translation:
                address: 192.168.1.10
                port: "8080"
    state: rendered

# Using parsed
- name: Parse NAT configuration from file
  vyos.vyos.vyos_nat:
    running_config: "{{ lookup('file', './nat_config.cfg') }}"
    state: parsed

Return Values

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

Key	Description
after dictionary	The resulting configuration after module execution. Returned: when changed Sample: "This output will always be in the same format as the module argspec.\n"
before dictionary	The configuration prior to the module execution. Returned: when state is merged, replaced, overridden or deleted Sample: "This output will always be in the same format as the module argspec.\n"
commands list / elements=string	The set of commands pushed to the remote device. Returned: when state is merged, replaced, overridden or deleted Sample: ["set nat destination rule 100 description 'Web server NAT'", "set nat destination rule 100 protocol tcp", "set nat destination rule 100 inbound-interface name eth2", "set nat destination rule 100 destination address 198.51.100.10", "set nat destination rule 100 translation address 192.168.1.10", "delete nat source rule 200"]
gathered dictionary	Facts about the network resource gathered from the remote device as structured data. Returned: when state is gathered Sample: "This output will always be in the same format as the module argspec.\n"
parsed dictionary	The device native config provided in running_config option parsed into structured data as per module argspec. Returned: when state is parsed Sample: "This output will always be in the same format as the module argspec.\n"
rendered list / elements=string	The provided configuration in the task rendered in device-native format (offline). Returned: when state is rendered Sample: ["set nat destination rule 100 description 'Web server NAT'", "set nat destination rule 100 protocol tcp", "set nat destination rule 100 inbound-interface name eth2", "set nat destination rule 100 destination address 198.51.100.10", "set nat destination rule 100 translation address 192.168.1.10"]

Authors

• Evgeny Molotkov (@omnom62)

Collection links

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