ios_l3_interfaces – Manage Layer-3 interface on Cisco IOS devices
New in version 2.9.
Synopsis
- This module provides declarative management of Layer-3 interface on Cisco IOS devices.
Parameters
| Parameter | Choices/Defaults | Comments | ||
|---|---|---|---|---|
| config
list / elements=dictionary
|
A dictionary of Layer-3 interface options
|
|||
| ipv4
list / elements=dictionary
|
IPv4 address to be set for the Layer-3 interface mentioned in name option. The address format is <ipv4 address>/<mask>, the mask is number in range 0-32 eg. 192.168.0.1/24.
|
|||
| address
string
|
Configures the IPv4 address for Interface.
|
|||
| dhcp_client
integer
|
Configures and specifies client-id to use over DHCP ip. Note, This option shall work only when dhcp is configured as IP.
GigabitEthernet interface number
|
|||
| dhcp_hostname
string
|
Configures and specifies value for hostname option over DHCP ip. Note, This option shall work only when dhcp is configured as IP.
|
|||
| secondary
boolean
|
|
Configures the IP address as a secondary address.
|
||
| ipv6
list / elements=dictionary
|
IPv6 address to be set for the Layer-3 interface mentioned in name option.
The address format is <ipv6 address>/<mask>, the mask is number in range 0-128 eg. fd5d:12c9:2201:1::1/64
|
|||
| address
string
|
Configures the IPv6 address for Interface.
|
|||
| name
string / required
|
Full name of the interface excluding any logical unit number, i.e. GigabitEthernet0/1.
|
|||
| state
string
|
|
The state of the configuration after module completion
|
||
Examples
---
# Using merged
#
# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# description Configured by Ansible
# ip address 10.1.1.1 255.255.255.0
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description This is test
# no ip address
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# description Configured by Ansible Network
# no ip address
# interface GigabitEthernet0/3.100
# encapsulation dot1Q 20
- name: Merge provided configuration with device configuration
ios_l3_interfaces:
config:
- name: GigabitEthernet0/1
ipv4:
- address: 192.168.0.1/24
secondary: True
- name: GigabitEthernet0/2
ipv4:
- address: 192.168.0.2/24
- name: GigabitEthernet0/3
ipv6:
- address: fd5d:12c9:2201:1::1/64
- name: GigabitEthernet0/3.100
ipv4:
- address: 192.168.0.3/24
state: merged
# After state:
# ------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# description Configured by Ansible
# ip address 10.1.1.1 255.255.255.0
# ip address 192.168.0.1 255.255.255.0 secondary
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description This is test
# ip address 192.168.0.2 255.255.255.0
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# description Configured by Ansible Network
# ipv6 address FD5D:12C9:2201:1::1/64
# interface GigabitEthernet0/3.100
# encapsulation dot1Q 20
# ip address 192.168.0.3 255.255.255.0
# Using replaced
#
# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# description Configured by Ansible
# ip address 10.1.1.1 255.255.255.0
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description This is test
# no ip address
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# description Configured by Ansible Network
# ip address 192.168.2.0 255.255.255.0
# interface GigabitEthernet0/3.100
# encapsulation dot1Q 20
# ip address 192.168.0.2 255.255.255.0
- name: Replaces device configuration of listed interfaces with provided configuration
ios_l3_interfaces:
config:
- name: GigabitEthernet0/2
ipv4:
- address: 192.168.2.0/24
- name: GigabitEthernet0/3
ipv4:
- address: dhcp
dhcp_client: 2
dhcp_hostname: test.com
- name: GigabitEthernet0/3.100
ipv4:
- address: 192.168.0.3/24
secondary: True
state: replaced
# After state:
# ------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# description Configured by Ansible
# ip address 10.1.1.1 255.255.255.0
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description This is test
# ip address 192.168.2.1 255.255.255.0
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# description Configured by Ansible Network
# ip address dhcp client-id GigabitEthernet0/2 hostname test.com
# interface GigabitEthernet0/3.100
# encapsulation dot1Q 20
# ip address 192.168.0.2 255.255.255.0
# ip address 192.168.0.3 255.255.255.0 secondary
# Using overridden
#
# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# description Configured by Ansible
# ip address 10.1.1.1 255.255.255.0
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description This is test
# ip address 192.168.2.1 255.255.255.0
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# description Configured by Ansible Network
# ipv6 address FD5D:12C9:2201:1::1/64
# interface GigabitEthernet0/3.100
# encapsulation dot1Q 20
# ip address 192.168.0.2 255.255.255.0
- name: Override device configuration of all interfaces with provided configuration
ios_l3_interfaces:
config:
- name: GigabitEthernet0/2
ipv4:
- address: 192.168.0.1/24
- name: GigabitEthernet0/3.100
ipv6:
- address: autoconfig
state: overridden
# After state:
# ------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# description Configured by Ansible
# no ip address
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description This is test
# ip address 192.168.0.1 255.255.255.0
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# description Configured by Ansible Network
# interface GigabitEthernet0/3.100
# encapsulation dot1Q 20
# ipv6 address autoconfig
# Using Deleted
#
# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# ip address 192.0.2.10 255.255.255.0
# shutdown
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description Configured by Ansible Network
# ip address 192.168.1.0 255.255.255.0
# interface GigabitEthernet0/3
# description Configured by Ansible Network
# ip address 192.168.0.1 255.255.255.0
# shutdown
# duplex full
# speed 10
# ipv6 address FD5D:12C9:2201:1::1/64
# interface GigabitEthernet0/3.100
# encapsulation dot1Q 20
# ip address 192.168.0.2 255.255.255.0
- name: "Delete attributes of given interfaces (NOTE: This won't delete the interface itself)"
ios_l3_interfaces:
config:
- name: GigabitEthernet0/2
- name: GigabitEthernet0/3.100
state: deleted
# After state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# no ip address
# shutdown
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description Configured by Ansible Network
# no ip address
# interface GigabitEthernet0/3
# description Configured by Ansible Network
# ip address 192.168.0.1 255.255.255.0
# shutdown
# duplex full
# speed 10
# ipv6 address FD5D:12C9:2201:1::1/64
# interface GigabitEthernet0/3.100
# encapsulation dot1Q 20
# Using Deleted without any config passed
#"(NOTE: This will delete all of configured L3 resource module attributes from each configured interface)"
#
# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# ip address 192.0.2.10 255.255.255.0
# shutdown
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description Configured by Ansible Network
# ip address 192.168.1.0 255.255.255.0
# interface GigabitEthernet0/3
# description Configured by Ansible Network
# ip address 192.168.0.1 255.255.255.0
# shutdown
# duplex full
# speed 10
# ipv6 address FD5D:12C9:2201:1::1/64
# interface GigabitEthernet0/3.100
# encapsulation dot1Q 20
# ip address 192.168.0.2 255.255.255.0
- name: "Delete L3 attributes of ALL interfaces together (NOTE: This won't delete the interface itself)"
ios_l3_interfaces:
state: deleted
# After state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# no ip address
# shutdown
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description Configured by Ansible Network
# no ip address
# interface GigabitEthernet0/3
# description Configured by Ansible Network
# shutdown
# duplex full
# speed 10
# interface GigabitEthernet0/3.100
# encapsulation dot1Q 20
Return Values
Common return values are documented here, the following are the fields unique to this module:
| Key | Returned | Description |
|---|---|---|
| after
list
|
when changed |
The configuration as structured data after module completion.
Sample:
The configuration returned will always be in the same format of the parameters above.
|
| before
list
|
always |
The configuration as structured data prior to module invocation.
Sample:
The configuration returned will always be in the same format of the parameters above.
|
| commands
list
|
always |
The set of commands pushed to the remote device
Sample:
['interface GigabitEthernet0/1', 'ip address 192.168.0.2 255.255.255.0']
|
Status
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Network Team. [network]
Red Hat Support
More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.
Authors
- Sumit Jaiswal (@justjais)
Hint
If you notice any issues in this documentation, you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.9/modules/ios_l3_interfaces_module.html