# ios_vlans – Manage VLANs on Cisco IOS devices

New in version 2.9.

- Synopsis
- Parameters
- Notes
- Examples
- Return Values
- Status

## Synopsis

- This module provides declarative management of VLANs on Cisco IOS network devices.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
config list / elements=dictionary |  | A dictionary of VLANs options
| mtu integer |  | VLAN Maximum Transmission Unit. Refer to vendor documentation for valid values.
| name string |  | Ascii name of the VLAN. NOTE, name should not be named/appended with default as it is reserved for device default vlans.

remote_span
boolean

Choices:
- no
- yes

Configure as Remote SPAN VLAN

shutdown
string

Choices:
- enabled
- disabled

Shutdown VLAN switching.

state
string

Choices:
- active
- suspend

Operational state of the VLAN

| vlan_id integer / required |  | ID of the VLAN. Range 1-4094

state
string

Choices:
- merged ←
- replaced
- overridden
- deleted

The state of the configuration after module completion

## Notes

Note

- Tested against Cisco IOSv Version 15.2 on VIRL
- This module works with connection `network_cli`. See IOS Platform Options.

## Examples

    ---
    # Using merged

    # Before state:
    # -------------
    #
    # vios#show vlan
    # VLAN Name                             Status    Ports
    # ---- -------------------------------- --------- -------------------------------
    # 1    default                          active    Gi0/1, Gi0/2
    # 1002 fddi-default                     act/unsup
    # 1003 token-ring-default               act/unsup
    # 1004 fddinet-default                  act/unsup
    # 1005 trnet-default                    act/unsup
    #
    # VLAN Type  SAID       MTU   Parent RingNo BridgeNo Stp  BrdgMode Trans1 Trans2
    # ---- ----- ---------- ----- ------ ------ -------- ---- -------- ------ ------
    # 1    enet  100001     1500  -      -      -        -    -        0      0
    # 1002 fddi  101002     1500  -      -      -        -    -        0      0
    # 1003 tr    101003     1500  -      -      -        -    -        0      0
    # 1004 fdnet 101004     1500  -      -      -        ieee -        0      0
    # 1005 trnet 101005     1500  -      -      -        ibm  -        0      0

    - name: Merge provided configuration with device configuration
      ios_vlans:
        config:
          - name: Vlan_10
            vlan_id: 10
            state: active
            shutdown: disabled
            remote_span: 10
          - name: Vlan_20
            vlan_id: 20
            mtu: 610
            state: active
            shutdown: enabled
          - name: Vlan_30
            vlan_id: 30
            state: suspend
            shutdown: enabled
        state: merged

    # After state:
    # ------------
    #
    # vios#show vlan
    # VLAN Name                             Status    Ports
    # ---- -------------------------------- --------- -------------------------------
    # 1    default                          active    Gi0/1, Gi0/2
    # 10   vlan_10                          active
    # 20   vlan_20                          act/lshut
    # 30   vlan_30                          sus/lshut
    # 1002 fddi-default                     act/unsup
    # 1003 token-ring-default               act/unsup
    # 1004 fddinet-default                  act/unsup
    # 1005 trnet-default                    act/unsup
    #
    # VLAN Type  SAID       MTU   Parent RingNo BridgeNo Stp  BrdgMode Trans1 Trans2
    # ---- ----- ---------- ----- ------ ------ -------- ---- -------- ------ ------
    # 1    enet  100001     1500  -      -      -        -    -        0      0
    # 10   enet  100010     1500  -      -      -        -    -        0      0
    # 20   enet  100020     610   -      -      -        -    -        0      0
    # 30   enet  100030     1500  -      -      -        -    -        0      0
    # 1002 fddi  101002     1500  -      -      -        -    -        0      0
    # 1003 tr    101003     1500  -      -      -        -    -        0      0
    # 1004 fdnet 101004     1500  -      -      -        ieee -        0      0
    # 1005 trnet 101005     1500  -      -      -        ibm  -        0      0
    #
    # Remote SPAN VLANs
    # ------------------------------------------------------------------------------
    # 10

    # Using overridden

    # Before state:
    # -------------
    #
    # vios#show vlan
    # VLAN Name                             Status    Ports
    # ---- -------------------------------- --------- -------------------------------
    # 1    default                          active    Gi0/1, Gi0/2
    # 10   vlan_10                          active
    # 20   vlan_20                          act/lshut
    # 30   vlan_30                          sus/lshut
    # 1002 fddi-default                     act/unsup
    # 1003 token-ring-default               act/unsup
    # 1004 fddinet-default                  act/unsup
    # 1005 trnet-default                    act/unsup
    #
    # VLAN Type  SAID       MTU   Parent RingNo BridgeNo Stp  BrdgMode Trans1 Trans2
    # ---- ----- ---------- ----- ------ ------ -------- ---- -------- ------ ------
    # 1    enet  100001     1500  -      -      -        -    -        0      0
    # 10   enet  100010     1500  -      -      -        -    -        0      0
    # 20   enet  100020     610   -      -      -        -    -        0      0
    # 30   enet  100030     1500  -      -      -        -    -        0      0
    # 1002 fddi  101002     1500  -      -      -        -    -        0      0
    # 1003 tr    101003     1500  -      -      -        -    -        0      0
    # 1004 fdnet 101004     1500  -      -      -        ieee -        0      0
    # 1005 trnet 101005     1500  -      -      -        ibm  -        0      0
    #
    # Remote SPAN VLANs
    # ------------------------------------------------------------------------------
    # 10

    - name: Override device configuration of all VLANs with provided configuration
      ios_vlans:
        config:
          - name: Vlan_10
            vlan_id: 10
            mtu: 1000
        state: overridden

    # After state:
    # ------------
    #
    # vios#show vlan
    # VLAN Name                             Status    Ports
    # ---- -------------------------------- --------- -------------------------------
    # 10   Vlan_10                          active
    #
    # VLAN Type  SAID       MTU   Parent RingNo BridgeNo Stp  BrdgMode Trans1 Trans2
    # ---- ----- ---------- ----- ------ ------ -------- ---- -------- ------ ------
    # 10   enet  100010     1000  -      -      -        -    -        0      0

    # Using replaced

    # Before state:
    # -------------
    #
    # vios#show vlan
    # VLAN Name                             Status    Ports
    # ---- -------------------------------- --------- -------------------------------
    # 1    default                          active    Gi0/1, Gi0/2
    # 10   vlan_10                          active
    # 20   vlan_20                          act/lshut
    # 30   vlan_30                          sus/lshut
    # 1002 fddi-default                     act/unsup
    # 1003 token-ring-default               act/unsup
    # 1004 fddinet-default                  act/unsup
    # 1005 trnet-default                    act/unsup
    #
    # VLAN Type  SAID       MTU   Parent RingNo BridgeNo Stp  BrdgMode Trans1 Trans2
    # ---- ----- ---------- ----- ------ ------ -------- ---- -------- ------ ------
    # 1    enet  100001     1500  -      -      -        -    -        0      0
    # 10   enet  100010     1500  -      -      -        -    -        0      0
    # 20   enet  100020     610   -      -      -        -    -        0      0
    # 30   enet  100030     1500  -      -      -        -    -        0      0
    # 1002 fddi  101002     1500  -      -      -        -    -        0      0
    # 1003 tr    101003     1500  -      -      -        -    -        0      0
    # 1004 fdnet 101004     1500  -      -      -        ieee -        0      0
    # 1005 trnet 101005     1500  -      -      -        ibm  -        0      0
    #
    # Remote SPAN VLANs
    # ------------------------------------------------------------------------------
    # 10

    - name: Replaces device configuration of listed VLANs with provided configuration
      ios_vlans:
        config:
          - vlan_id: 20
            name: Test_VLAN20
            mtu: 700
            shutdown: disabled
          - vlan_id: 30
            name: Test_VLAN30
            mtu: 1000
        state: replaced

    # After state:
    # ------------
    #
    # vios#show vlan
    # VLAN Name                             Status    Ports
    # ---- -------------------------------- --------- -------------------------------
    # 1    default                          active    Gi0/1, Gi0/2
    # 10   vlan_10                          active
    # 20   Test_VLAN20                      active
    # 30   Test_VLAN30                      sus/lshut
    # 1002 fddi-default                     act/unsup
    # 1003 token-ring-default               act/unsup
    # 1004 fddinet-default                  act/unsup
    # 1005 trnet-default                    act/unsup
    #
    # VLAN Type  SAID       MTU   Parent RingNo BridgeNo Stp  BrdgMode Trans1 Trans2
    # ---- ----- ---------- ----- ------ ------ -------- ---- -------- ------ ------
    # 1    enet  100001     1500  -      -      -        -    -        0      0
    # 10   enet  100010     1500  -      -      -        -    -        0      0
    # 20   enet  100020     700   -      -      -        -    -        0      0
    # 30   enet  100030     1000  -      -      -        -    -        0      0
    # 1002 fddi  101002     1500  -      -      -        -    -        0      0
    # 1003 tr    101003     1500  -      -      -        -    -        0      0
    # 1004 fdnet 101004     1500  -      -      -        ieee -        0      0
    # 1005 trnet 101005     1500  -      -      -        ibm  -        0      0
    #
    # Remote SPAN VLANs
    # ------------------------------------------------------------------------------
    # 10

    # Using deleted

    # Before state:
    # -------------
    #
    # vios#show vlan
    # VLAN Name                             Status    Ports
    # ---- -------------------------------- --------- -------------------------------
    # 1    default                          active    Gi0/1, Gi0/2
    # 10   vlan_10                          active
    # 20   vlan_20                          act/lshut
    # 30   vlan_30                          sus/lshut
    # 1002 fddi-default                     act/unsup
    # 1003 token-ring-default               act/unsup
    # 1004 fddinet-default                  act/unsup
    # 1005 trnet-default                    act/unsup
    #
    # VLAN Type  SAID       MTU   Parent RingNo BridgeNo Stp  BrdgMode Trans1 Trans2
    # ---- ----- ---------- ----- ------ ------ -------- ---- -------- ------ ------
    # 1    enet  100001     1500  -      -      -        -    -        0      0
    # 10   enet  100010     1500  -      -      -        -    -        0      0
    # 20   enet  100020     610   -      -      -        -    -        0      0
    # 30   enet  100030     1500  -      -      -        -    -        0      0
    # 1002 fddi  101002     1500  -      -      -        -    -        0      0
    # 1003 tr    101003     1500  -      -      -        -    -        0      0
    # 1004 fdnet 101004     1500  -      -      -        ieee -        0      0
    # 1005 trnet 101005     1500  -      -      -        ibm  -        0      0
    #
    # Remote SPAN VLANs
    # ------------------------------------------------------------------------------
    # 10

    - name: Delete attributes of given VLANs
      ios_vlans:
        config:
          - vlan_id: 10
          - vlan_id: 20
        state: deleted

    # After state:
    # -------------
    #
    # vios#show vlan
    # VLAN Name                             Status    Ports
    # ---- -------------------------------- --------- -------------------------------
    # 1    default                          active    Gi0/1, Gi0/2
    # 30   vlan_30                          sus/lshut
    # 1002 fddi-default                     act/unsup
    # 1003 token-ring-default               act/unsup
    # 1004 fddinet-default                  act/unsup
    # 1005 trnet-default                    act/unsup
    #
    # VLAN Type  SAID       MTU   Parent RingNo BridgeNo Stp  BrdgMode Trans1 Trans2
    # ---- ----- ---------- ----- ------ ------ -------- ---- -------- ------ ------
    # 1    enet  100001     1500  -      -      -        -    -        0      0
    # 30   enet  100030     1500  -      -      -        -    -        0      0
    # 1002 fddi  101002     1500  -      -      -        -    -        0      0
    # 1003 tr    101003     1500  -      -      -        -    -        0      0
    # 1004 fdnet 101004     1500  -      -      -        ieee -        0      0
    # 1005 trnet 101005     1500  -      -      -        ibm  -        0      0

    # Using Deleted without any config passed
    #"(NOTE: This will delete all of configured vlans attributes)"

    # Before state:
    # -------------
    #
    # vios#show vlan
    # VLAN Name                             Status    Ports
    # ---- -------------------------------- --------- -------------------------------
    # 1    default                          active    Gi0/1, Gi0/2
    # 10   vlan_10                          active
    # 20   vlan_20                          act/lshut
    # 30   vlan_30                          sus/lshut
    # 1002 fddi-default                     act/unsup
    # 1003 token-ring-default               act/unsup
    # 1004 fddinet-default                  act/unsup
    # 1005 trnet-default                    act/unsup
    #
    # VLAN Type  SAID       MTU   Parent RingNo BridgeNo Stp  BrdgMode Trans1 Trans2
    # ---- ----- ---------- ----- ------ ------ -------- ---- -------- ------ ------
    # 1    enet  100001     1500  -      -      -        -    -        0      0
    # 10   enet  100010     1500  -      -      -        -    -        0      0
    # 20   enet  100020     610   -      -      -        -    -        0      0
    # 30   enet  100030     1500  -      -      -        -    -        0      0
    # 1002 fddi  101002     1500  -      -      -        -    -        0      0
    # 1003 tr    101003     1500  -      -      -        -    -        0      0
    # 1004 fdnet 101004     1500  -      -      -        ieee -        0      0
    # 1005 trnet 101005     1500  -      -      -        ibm  -        0      0
    #
    # Remote SPAN VLANs
    # ------------------------------------------------------------------------------
    # 10

    - name: Delete attributes of ALL VLANs
      ios_vlans:
        state: deleted

    # After state:
    # -------------
    #
    # vios#show vlan
    # VLAN Name                             Status    Ports
    # ---- -------------------------------- --------- -------------------------------
    # 1    default                          active    Gi0/1, Gi0/2
    # 1002 fddi-default                     act/unsup
    # 1003 token-ring-default               act/unsup
    # 1004 fddinet-default                  act/unsup
    # 1005 trnet-default                    act/unsup
    #
    # VLAN Type  SAID       MTU   Parent RingNo BridgeNo Stp  BrdgMode Trans1 Trans2
    # ---- ----- ---------- ----- ------ ------ -------- ---- -------- ------ ------
    # 1    enet  100001     1500  -      -      -        -    -        0      0
    # 1002 fddi  101002     1500  -      -      -        -    -        0      0
    # 1003 tr    101003     1500  -      -      -        -    -        0      0
    # 1004 fdnet 101004     1500  -      -      -        ieee -        0      0
    # 1005 trnet 101005     1500  -      -      -        ibm  -        0      0

## 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: ['vlan 20', 'name vlan_20', 'mtu 600', 'remote-span']

## 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.