.. _vyos.vyos.vyos_nat_module: ****************** vyos.vyos.vyos_nat ****************** **NAT resource module** Version added: 6.0.0 .. contents:: :local: :depth: 1 Synopsis -------- - This module manages NAT configuration on devices running VyOS. Parameters ---------- .. raw:: html
Parameter Choices/Defaults 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
    Choices:
  • no
  • yes
Log CGNAT address allocations.
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
    Choices:
  • no
  • yes
Disable this destination NAT rule.
exclude
boolean
    Choices:
  • no
  • yes
Exclude packets matching this rule from NAT.
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
    Choices:
  • source-address
  • destination-address
  • source-port
  • destination-port
  • random
Fields to hash on for load balancing. Mutually exclusive with translation.address.
log
boolean
    Choices:
  • no
  • yes
Log packets hitting this rule.
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
    Choices:
  • random
  • persistent
Address mapping mode for translation.
port
string
Port number or range to translate destination port to.
port_mapping
string
    Choices:
  • random
  • none
Port mapping mode for translation.
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
    Choices:
  • no
  • yes
Disable this source NAT rule.
exclude
boolean
    Choices:
  • no
  • yes
Exclude packets matching this rule from NAT.
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
    Choices:
  • source-address
  • destination-address
  • source-port
  • destination-port
  • random
Fields to hash on for load balancing. Mutually exclusive with translation.address.
log
boolean
    Choices:
  • no
  • yes
Log packets hitting this rule.
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
    Choices:
  • random
  • persistent
Address mapping mode for translation.
port
string
Port number or range to translate source port to.
port_mapping
string
    Choices:
  • random
  • none
Port mapping mode for translation.
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
    Choices:
  • no
  • yes
Log packets hitting this static NAT rule.
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
    Choices:
  • no
  • yes
Disable this NAT64 source rule.
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
    Choices:
  • no
  • yes
Disable this translation pool.
id
integer / required
Pool number (1-999999).
port
string
Port number or range for translation pool.
protocol
string
    Choices:
  • icmp
  • tcp
  • udp
Protocol for this translation pool entry.
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
    Choices:
  • no
  • yes
Disable this NAT66 destination rule.
exclude
boolean
    Choices:
  • no
  • yes
Exclude packets matching this rule from NAT66.
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
    Choices:
  • no
  • yes
Log packets hitting this NAT66 destination rule.
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
    Choices:
  • no
  • yes
Disable this NAT66 source rule.
exclude
boolean
    Choices:
  • no
  • yes
Exclude packets matching this rule from NAT66.
id
integer / required
Rule number for NAT66 source rule.
log
boolean
    Choices:
  • no
  • yes
Log packets hitting this NAT66 source rule.
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
    Choices:
  • deleted
  • merged ←
  • overridden
  • replaced
  • gathered
  • rendered
  • parsed
The state the configuration should be left in.

Notes ----- .. note:: - Tested against VyOS 1.4.3 and 1.5.0. - This module works with connection ``network_cli``. Examples -------- .. code-block:: yaml # 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: .. raw:: html
Key Returned Description
after
dictionary
when changed
The resulting configuration after module execution.

Sample:
This output will always be in the same format as the module argspec.
before
dictionary
when state is merged, replaced, overridden or deleted
The configuration prior to the module execution.

Sample:
This output will always be in the same format as the module argspec.
commands
list
when state is merged, replaced, overridden or deleted
The set of commands pushed to the remote device.

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
when state is gathered
Facts about the network resource gathered from the remote device as structured data.

Sample:
This output will always be in the same format as the module argspec.
parsed
dictionary
when state is parsed
The device native config provided in running_config option parsed into structured data as per module argspec.

Sample:
This output will always be in the same format as the module argspec.
rendered
list
when state is rendered
The provided configuration in the task rendered in device-native format (offline).

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']


Status ------ Authors ~~~~~~~ - Evgeny Molotkov (@omnom62)