cisco.nxos.nxos_l3_interfaces module – L3 interfaces resource module

Note

This module is part of the cisco.nxos collection (version 11.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 cisco.nxos.

To use it in a playbook, specify: cisco.nxos.nxos_l3_interfaces.

New in cisco.nxos 1.0.0

Synopsis
Parameters
Notes
Examples
Return Values

Synopsis

This module manages Layer-3 interfaces attributes of NX-OS Interfaces.

Note

This module has a corresponding action plugin.

Aliases: l3_interfaces

Parameters

Parameter	Comments
config list / elements=dictionary	A dictionary of Layer-3 interface options
bandwidth dictionary	Manually set the bandwidth
inherit boolean	Specify that bandwidth is inherited Choices: `false` `true`
kilobits integer	Bandwidth in kilobits
dhcp dictionary	Configure DHCP snooping or relay
ipv4 dictionary	DHCP snooping for ipv4
option82 dictionary	DHCP option82.
suboption dictionary	DHCP option82.
circuit_id string	DHCP option82 suboption circuit-id string configuration.
relay dictionary	Configure relay agent.
address list / elements=dictionary	List of ipv4 relay addresses
relay_ip string	IP address
vrf_name string	Helper address VRF membership
information dictionary	Relay agent information option.
trusted boolean	Enable relay trust on this interface. Choices: `false` `true`
source_interface dictionary	Configure gateway address for DHCP relay
interface_id string	Interface ID
interface_type string	Type of interface
subnet_selection dictionary	Configure gateway address for DHCP relay
subnet_ip string	IP address
smart_relay boolean	Configure DHCP smart relay on interface. Choices: `false` `true`
ipv6 dictionary	DHCP snooping for ipv6
relay dictionary	Configure relay agent.
address list / elements=dictionary	Configure DHCPv6 server relay address
interface_id string	Interface ID
interface_type string	Type of interface
relay_ip string	IP address
vrf_name string	Helper address VRF membership
source_interface dictionary	Configure source interface for DHCPv6 relay.
interface_id string	Interface ID
interface_type string	Type of interface
smart_relay boolean	Configure DHCP smart relay on interface. Choices: `false` `true`
dot1q integer	Configures IEEE 802.1Q VLAN encapsulation on a subinterface.
evpn_multisite_tracking string added in cisco.nxos 1.1.0	VxLAN evpn multisite Interface tracking. Supported only on selected model. Choices: `"fabric-tracking"` `"dci-tracking"`
ipv4 list / elements=dictionary	IPv4 address and attributes of the L3 interface.
address string	IPV4 address of the L3 interface.
ip_network_mask string	IP prefix and network mask length in format x.x.x.x/m or IP network mask in format m.m.m.m
route_preference integer	URIB route preference for local/direct routes
secondary boolean	A boolean attribute to manage addition of secondary IP address. Choices: `false` `true`
tag integer	URIB route tag value for local/direct routes.
ipv6 list / elements=dictionary	IPv6 address and attributes of the L3 interface.
address string	IPV6 address of the L3 interface.
aggregate_prefix_length integer	Prefix-Length for AM Route Aggregation
anycast boolean	Configure IPv6 anycast address on interface Choices: `false` `true`
eui64 boolean	Configure Extended Unique Identifier for the low-order 64 bits Choices: `false` `true`
route_preference integer	URIB route preference for local/direct routes
tag integer	URIB route tag value for local/direct routes.
use_bia boolean	Use BIA Choices: `false` `true`
ipv6_redirects boolean	Enables/disables ipv6 redirects. Choices: `false` `true`
ipv6_unreachables boolean	Enables/disables ip redirects. Choices: `false` `true`
ipv6_verify dictionary	Unicast Reverse Path Forwarding.
unicast dictionary	Unicast Reverse Path Forwarding.
source dictionary	Validation of source address.
reachable_via dictionary	Specify reachability check to apply to the source address.
allow_default boolean	Loose Default Route Unicast Reverse Path Forwarding. Choices: `false` `true`
mode string	Source is reachable via any/rx interface.
mac_address string	Manually set interface MAC address or extract the MAC address (3) from the IPv6 address configured on the interface.
name string / required	Full name of L3 interface, i.e. Ethernet1/1.
port_unreachable boolean	Enable sending ICMP port-unreachable. Choices: `false` `true`
proxy_arp boolean	Configure proxy ARP. Choices: `false` `true`
redirects boolean	Enables/disables ipv4 redirects. Choices: `false` `true`
unreachables boolean	Enables/disables ip redirects. Choices: `false` `true`
verify dictionary	Configure Unicast Reverse Path Forwarding or IP Source Guard.
unicast dictionary	Unicast Reverse Path Forwarding.
source dictionary	Validation of source address.
reachable_via dictionary	Specify reachability check to apply to the source address.
allow_default boolean	Loose Default Route Unicast Reverse Path Forwarding. Choices: `false` `true`
mode string	Source is reachable via any/rx interface.
running_config string	This option is used only with state parsed. The value of this option should be the output received from the IOS device by executing the command show running-config \| section ^interface. The state parsed reads the configuration from `running_config` option and transforms it into Ansible structured data as per the resource module’s argspec and the value is then returned in the parsed key within the result.
state string	The state the configuration should be left in The states rendered, gathered and parsed does not perform any change on the device. The state rendered will transform the configuration in `config` option to platform specific CLI commands which will be returned in the rendered key within the result. For state rendered active connection to remote host is not required. The state gathered will fetch the running configuration from device and transform it into structured data in the format as per the resource module argspec and the value is returned in the gathered key within the result. The state parsed reads the configuration from `running_config` option and transforms it into JSON format as per the resource module parameters and the value is returned in the parsed key within the result. The value of `running_config` option should be the same format as the output of command show running-config \| section ^interface executed on device. For state parsed active connection to remote host is not required. Choices: `"merged"` ← (default) `"replaced"` `"overridden"` `"deleted"` `"rendered"` `"gathered"` `"parsed"`

Notes

Note

Tested against NXOS 7.3.(0)D1(1) on VIRL
Unsupported for Cisco MDS

Examples

# Using merged

# Before state:
# -------------
#
# router# show running-config | section interface
# interface Ethernet1/1
# interface Ethernet1/2

- name: Merge provided configuration with device configuration.
  cisco.nxos.nxos_l3_interfaces:
    config:
      - name: Ethernet1/1
        mac_address: 0011.2233.4455
        ipv4:
          verify:
            unicast:
              source:
                reachable_via:
                  mode: any
                  allow_default: true
          dhcp:
            relay:
              address:
                - relay_ip: 11.0.0.1
                  vrf_name: abc
      - name: Ethernet1/2
        ipv6:
          addresses:
            - ipv6_address: 2001:db8::1/32
              route_preference: 70
              tag: 97
          dhcp:
            relay:
              address:
                - relay_ip: 2001:db8::1:abcd
    state: merged

# Task Output
# -----------
#
# before:
# - name: Ethernet1/1
# - name: Ethernet1/2
# commands:
# - interface Ethernet1/1
# - mac-address 0011.2233.4455
# - ip verify unicast source reachable-via any allow-default
# - ip dhcp relay address 11.0.0.1 use-vrf abc
# - interface Ethernet1/2
# - ipv6 address 2001:db8::1/32 route-preference 70 tag 97
# - ipv6 dhcp relay address 2001:db8::1:abcd
# after:
# - name: Ethernet1/1
#   mac_address: 0011.2233.4455
#   ipv4:
#     verify:
#       unicast:
#         source:
#           reachable_via:
#             mode: any
#             allow_default: true
#     dhcp:
#       relay:
#         address:
#           - relay_ip: 11.0.0.1
#             vrf_name: abc
# - name: Ethernet1/2
#   ipv6:
#     addresses:
#       - ipv6_address: 2001:db8::1/32
#         route_preference: 70
#         tag: 97
#     dhcp:
#       relay:
#         address:
#           - relay_ip: 2001:db8::1:abcd

# After state:
# ------------
#
# router# show running-config | section interface
# interface Ethernet1/1
#  mac-address 0011.2233.4455
#  ip verify unicast source reachable-via any allow-default
#  ip dhcp relay address 11.0.0.1 use-vrf abc
# interface Ethernet1/2
#  ipv6 address 2001:db8::1/32 route-preference 70 tag 97
#  ipv6 dhcp relay address 2001:db8::1:abcd


# Using replaced

# Before state:
# -------------
#
# router# show running-config | section interface
# interface Ethernet 1/1
#  mac-address 00:11:22:33:44:55
#  ip verify unicast source reachable-via any allow-default
#  ip dhcp relay address 11.0.0.1 use-vrf abc
# interface Ethernet 1/2
#  ipv6 dhcp relay address 2001:0db8::1:abcd
#  ipv6 address 2001:db8::1/32 route-preference 70 tag 97

- name: Replace device configuration of specified L3 interfaces with provided configuration.
  cisco.nxos.nxos_l3_interfaces:
    config:
      - name: Ethernet1/2
        mac_address: 0011.2233.4456
        ipv6:
          addresses:
            - ipv6_address: 2001:db8::1/32
              route_preference: 200
              tag: 22
          dhcp:
            relay:
              address:
                - relay_ip: 2001:db8::1:abcd
    state: replaced

# Task Output
# -----------
#
# before:
# - name: Ethernet1/1
#   mac_address: 0011.2233.4455
#   ipv4:
#     verify:
#       unicast:
#         source:
#           reachable_via:
#             mode: any
#             allow_default: true
#     dhcp:
#       relay:
#         address:
#           - relay_ip: 11.0.0.1
#             vrf_name: abc
# - name: Ethernet1/2
#   ipv6:
#     addresses:
#       - ipv6_address: 2001:db8::1/32
#         route_preference: 70
#         tag: 97
#     dhcp:
#       relay:
#         address:
#           - relay_ip: 2001:db8::1:abcd
# commands:
# - interface Ethernet1/2
# - no ipv6 address 2001:db8::1/32 route-preference 70 tag 97
# - ipv6 address 2001:db8::1/32 route-preference 200 tag 22
# - mac-address 0011.2233.4456
# after:
# - name: Ethernet1/1
#   mac_address: 0011.2233.4455
#   ipv4:
#     verify:
#       unicast:
#         source:
#           reachable_via:
#             mode: any
#             allow_default: true
#     dhcp:
#       relay:
#         address:
#           - relay_ip: 11.0.0.1
#             vrf_name: abc
# - name: Ethernet1/2
#   mac_address: 0011.2233.4456
#   ipv6:
#     addresses:
#       - ipv6_address: 2001:db8::1/32
#         route_preference: 200
#         tag: 22
#     dhcp:
#       relay:
#         address:
#           - relay_ip: 2001:db8::1:abcd

# After state:
# ------------
#
# router# show running-config | section interface
# interface Ethernet1/1
#  mac-address 0011.2233.4455
#  ip verify unicast source reachable-via any allow-default
#  ip dhcp relay address 11.0.0.1 use-vrf abc
# interface Ethernet1/2
#  mac-address 0011.2233.4456
#  ipv6 address 2001:db8::1/32 route-preference 200 tag 22
#  ipv6 dhcp relay address 2001:db8::1:abcd

# Using overridden

# Before state:
# -------------
#
# router# show running-config | section interface
# interface Ethernet 1/1
#  mac-address 00:11:22:33:44:55
#  ip verify unicast source reachable-via any allow-default
#  ip dhcp relay address 11.0.0.1 use-vrf abc
# interface Ethernet 1/2
#  ipv6 dhcp relay address 2001:0db8::1:abcd
#  ipv6 address 2001:db8::1/32 route-preference 70 tag 97

- name: Override device configuration with provided configuration.
  cisco.nxos.nxos_l3_interfaces:
    config:
      - name: Ethernet1/1
        mac_address: 0011.2233.4455
        ipv4:
          verify:
            unicast:
              source:
                reachable_via:
                  mode: any
                  allow_default: true
    state: overridden

# Task Output
# -----------
#
# before:
# before:
# - name: Ethernet1/1
#   mac_address: 0011.2233.4455
#   ipv4:
#     verify:
#       unicast:
#         source:
#           reachable_via:
#             mode: any
#             allow_default: true
#     dhcp:
#       relay:
#         address:
#           - relay_ip: 11.0.0.1
#             vrf_name: abc
# - name: Ethernet1/2
#   ipv6:
#     addresses:
#       - ipv6_address: 2001:db8::1/32
#         route_preference: 70
#         tag: 97
#     dhcp:
#       relay:
#         address:
#           - relay_ip: 2001:db8::1:abcd
# commands:
# - interface Ethernet1/1
# - no ip dhcp relay address 11.0.0.1 use-vrf abc
# - interface Ethernet1/2
# - no ipv6 address 2001:db8::1/32 route-preference 70 tag 97
# - no ipv6 dhcp relay address 2001:db8::1:abcd
# after:
# - name: Ethernet1/1
#   mac_address: 0011.2233.4455
#   ipv4:
#     verify:
#       unicast:
#         source:
#           reachable_via:
#             mode: any
#             allow_default: true
# - name: Ethernet1/2

# After state:
# ------------
#
# router# show running-config | section interface
# interface Ethernet1/1
#  mac-address 0011.2233.4455
#  ip verify unicast source reachable-via any allow-default

# Using deleted

# Before state:
# -------------
#
# router# show running-config | section interface
# interface Ethernet 1/1
#  mac-address 00:11:22:33:44:55
#  ip verify unicast source reachable-via any allow-default
#  ip dhcp relay address 11.0.0.1 use-vrf abc
# interface Ethernet 1/2
#  ipv6 dhcp relay address 2001:0db8::1:abcd
#  ipv6 address 2001:db8::1/32 route-preference 70 tag 97

- name: Delete L3 attributes of given interfaces (This won't delete the interface
    itself).
  cisco.nxos.nxos_l3_interfaces:
    config:
      - name: Ethernet1/1
      - name: Ethernet1/2
    state: deleted

# Task Output
# -----------
#
# before:
# - name: Ethernet1/1
#   mac_address: 0011.2233.4455
#   ipv4:
#     verify:
#       unicast:
#         source:
#           reachable_via:
#             mode: any
#             allow_default: true
#     dhcp:
#       relay:
#         address:
#           - relay_ip: 11.0.0.1
#             vrf_name: abc
# - name: Ethernet1/2
#   ipv6:
#     addresses:
#       - ipv6_address: 2001:db8::1/32
#         route_preference: 70
#         tag: 97
#     dhcp:
#       relay:
#         address:
#           - relay_ip: 2001:db8::1:abcd
# commands:
# - interface Ethernet1/1
# - no mac-address 0011.2233.4455
# - no ip verify unicast source reachable-via any allow-default
# - no ip dhcp relay address 11.0.0.1 use-vrf abc
# - interface Ethernet1/2
# - no ipv6 address 2001:db8::1/32 route-preference 70 tag 97
# - no ipv6 dhcp relay address 2001:db8::1:abcd
# after:
# - name: Ethernet1/1
# - name: Ethernet1/2

# After state:
# ------------
#
# router# show running-config | section interface
# interface Ethernet1/1
# interface Ethernet1/2

# Using rendered

- name: Use rendered state to convert task input to device specific commands
  cisco.nxos.nxos_l3_interfaces:
    config:
      - name: Ethernet1/1
        mac_address: 0011.2233.4455
        ipv4:
          verify:
            unicast:
              source:
                reachable_via:
                  mode: any
                  allow_default: true
          dhcp:
            relay:
              address:
                - relay_ip: 11.0.0.1
                  vrf_name: abc
      - name: Ethernet1/2
        ipv6:
          addresses:
            - ipv6_address: 2001:db8::1/32
              route_preference: 70
              tag: 97
          dhcp:
            relay:
              address:
                - relay_ip: 2001:db8::1:abcd
    state: rendered

# Task Output
# -----------
#
# rendered:
# - interface Ethernet1/1
# - mac-address 0011.2233.4455
# - ip verify unicast source reachable-via any allow-default
# - ip dhcp relay address 11.0.0.1 use-vrf abc
# - interface Ethernet1/2
# - ipv6 address 2001:db8::1/32 route-preference 70 tag 97
# - ipv6 dhcp relay address 2001:db8::1:abcd

# Using parsed

# parsed.cfg
# ----------
#
# interface Ethernet1/1
#  mac-address 0011.2233.4455
#  ip verify unicast source reachable-via any allow-default
#  ip dhcp relay address 11.0.0.1 use-vrf abc
# interface Ethernet1/2
#  ipv6 address 2001:db8::1/32 route-preference 70 tag 97
#  ipv6 dhcp relay address 2001:db8::1:abcd

- name: Use parsed state to convert externally supplied config to structured format
  cisco.nxos.nxos_l3_interfaces:
    running_config: "{{ lookup('file', 'parsed.cfg') }}"
    state: parsed

# Task output
# -----------
#
# parsed:
#   - name: Ethernet1/1
#     mac_address: 0011.2233.4455
#     ipv4:
#       verify:
#         unicast:
#           source:
#             reachable_via:
#               mode: any
#               allow_default: true
#       dhcp:
#         relay:
#           address:
#             - relay_ip: 11.0.0.1
#               vrf_name: abc
#   - name: Ethernet1/2
#     ipv6:
#       addresses:
#         - ipv6_address: 2001:db8::1/32
#           route_preference: 70
#           tag: 97
#       dhcp:
#         relay:
#           address:
#             - relay_ip: 2001:db8::1:abcd

# Using gathered

# Before state:
# -------------
#
# interface Ethernet 1/1
#  mac-address 00:11:22:33:44:55
#  ip verify unicast source reachable-via any allow-default
#  ip dhcp relay address 11.0.0.1 use-vrf abc
# interface Ethernet 1/2
#  ipv6 dhcp relay address 2001:0db8::1:abcd
#  ipv6 address 2001:db8::1/32 route-preference 70 tag 97

- name: Gather l3_interfaces facts from the device using nxos_l3_interfaces
  cisco.nxos.nxos_l3_interfaces:
    state: gathered

# Task output
# -----------
#
# gathered:
#   - name: Ethernet1/1
#     mac_address: 0011.2233.4455
#     ipv4:
#       verify:
#         unicast:
#           source:
#             reachable_via:
#               mode: any
#               allow_default: true
#       dhcp:
#         relay:
#           address:
#             - relay_ip: 11.0.0.1
#               vrf_name: abc
#   - name: Ethernet1/2
#     ipv6:
#       addresses:
#         - ipv6_address: 2001:db8::1/32
#           route_preference: 70
#           tag: 97
#       dhcp:
#         relay:
#           address:
#             - relay_ip: 2001:db8::1:abcd

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`, `deleted` or `purged` 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`, `deleted` or `purged` Sample: `["ip dhcp relay address 11.0.0.1 use-vrf abc", "ipv6 address 2001:db8::1/32 route-preference 70 tag 97", "ipv6 dhcp relay address 2001:db8::1:abcd"]`
gathered list / elements=string	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 list / elements=string	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: `["ip dhcp relay address 11.0.0.1 use-vrf abc", "ipv6 address 2001:db8::1/32 route-preference 70 tag 97", "ipv6 dhcp relay address 2001:db8::1:abcd"]`

Authors

Trishna Guha (@trishnaguha)
Nikhil Bhasin (@nickbhasin)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/cisco/nxos/nxos_l3_interfaces_module.html