WeOS
5.29.0

# Interface

## Introduction

A network interface handles configuration of the network layer in a computer network. It can be a representation of a hardware unit but it also be a pure software construction in case of a SSL interface or a loopback interface. It typically has a network address.

Related Examples and Use-Cases

- IPv6 Basic

## Overview

In its simplest case a interface is a higher layer representation of a network port in a 1-1 mapping. A more complex example is a VLAN interface that can contain several network ports. It handles the network layer which means it typically has a network address such as an IPV4 address. It also resolves mapping between network addresses and MAC addresses through ARP functionality.

For the image below two hosts are connected via ports eth1 on each unit. Host-1 have configured interface vlan1 with address 192.168.0.10/24 and Host-2 have configured vlan2 with address 192.168.0.20/24.

      Host-1                                          Host-2
     .-------.                                       .-------.
     |       |                                       |       |
     |       |                                       |       |
     |   1   |vlan1                             vlan2|   1   |
     '---+---'                                       '---+---'
         |.10                192.168.0.0/24           .20|
         +-----------------------------------------------+

## Configuration

Configuration of network interfaces is done in the iface context. Note that there are several configurable options which may not be relevant for each interface type. A custom MAC address and configuration options with respect to ARP are only relevant for interfaces which have a MAC address (LAN interfaces).

Example of how to configure interface vlan1:

    example:/#> configure
    example:/config/#> iface vlan1
    example:/config/iface-vlan1/#>

On VLAN interfaces, it is possible to circumvent the link status propagation property by configuring an interface as always up:

    example:/config/iface-vlan1/#> enable always

However, disabling link status propagation may significantly impact layer-3 protocols such as RIP, OSPF, VRRP, and more. The protocols will have to fall-back to other methods to detect link-down, e.g. hello message timeout and similar.

Do not use the enable always setting unless you really know what you are doing.

#### Syntax

`[no|show] inet [static IP/LEN|dhcp|ssl|link-local|ttdp]`

  This setting controls the handling of network addresses. It can be set and/or acquired in several ways.

  Note

  Enters a sub-configuration context for any inet specific settings.

  See Inet DHCP Configuration below for more details on DHCP client configuration.

  no
    No network address will be set
  static IP/LEN
    Configure a static [IP] address with network mask with length [LEN]
  dhcp
    Acquire a network address through the DHCP protocol
  ssl
    Acquire a network address through the SSL protocol
  link-local
    Acquire a network address through the link-local protocol
  ttdp
    Acquire a network address through the TTDP protocol
`[no|show] inet6 [static IP/LEN [eui-64] | link-local]`

  This settings controls how IPv6 addresses can be configured on the interface. Currently only static and link-local address methods are supported for IPv6 address configuration.

  Note

  For the IPv6 address to be added to the interface, global IPv6 functionality must be enabled on the device. This is done by enabling the global IPv6 functionality in the IPv6 configuration context. The below example is how it is done in the CLI:

      example:/#> configure
      example:/config/#> ipv6
      example:/config/ipv6/#> enable

  Note

  Enters a sub-configuration context for any inet6 settings that may be specific to the selected method.

  Examples

  Configuring a static IPv6 address:

      example:/config/iface-vlan1/#> inet6 static 2001:db8::1234:5678/64

  Configuring a link-local IPv6 address:

      example:/config/iface-vlan1/#> inet6 link-local

  no
    Remove configured IPv6 address method. If no specific inet6 method is specified, all configured IPv6 address methods will be removed.
  static IP/LEN [eui-64]

    Configure a static `IP` address with network mask with length `LEN`.

    If no `LEN` is provided, the default length of /64 will be used.

    The optional `eui-64` keyword can be used to enable EUI-64 address generation for the interface. The eui-64 address generation is based on the MAC address of the interface. The MAC address is split in half, and the 7th bit is flipped. The resulting half MAC address is then inserted in the middle of the IPv6 address. The initial part of the IPv6 address is taken from the provided static IP address.

    As en example, if the initial part of the provided IPv6 address is 2001:db8:8888:9999 and the MAC address of the interface is 00:11:22:33:44:55, the resulting IPv6 address will be 2001:db8:8888:9999:211:22ff:fe33:4455/64. This is how it would be configured in the CLI:

        example:/config/iface-vlan1/#> inet6 static 2001:db8:8888:9999::/64 eui-64

  link-local

    Specify that the interface should acquire a link-local IPv6 address.

    The link-local address is based on the MAC address of the interface. If the MAC address of the interface is 00:11:22:33:44:55, the resulting link-local address will be fe80::211:22ff:fe33:4455/64.

    Note

    Regardless of the selected IPv6 address method, the link-local address will always be enabled, even if it is not explicitly configured. The reason for this is that the link-local address is always required for IPv6 communication.

`[no] enable [always]`

  This setting controls the administrative state for the interface, if it should be UP or DOWN.

  Note

  If the interface is a VLAN interface and it is disabled, the CPU connection to that VLAN is also completely severed. Only layer-2 switching will work on this VLAN, while all layer-3 services such as management, routing, firewall, etc. will be disabled.

  If the intention is to disable the entire VLAN itself, that action is performed in the VLAN configuration context.

  Warning

  Disabling an interface may cause loss of connectivity to the device, which may require physical access to the device to restore connectivity. Be mindful of which interface, you may potentially be accessing the device over.

  no
    Administratively disable the interface.
  always

    When set, the interface will remain up even if the link is down.

    Note

    This setting only available for VLAN interfaces.

`[no] shutdown`

  Shutdown the interface, same as “no up”

  no
    Enable interface
`[no] mac [MAC]`

  Change or restore MAC address of interface.

  no
    Use default MAC address
`[no] mtu [68-1500]`

  Set maximum transfer unit, MTU, of interface.

  no
    Use default MTU size
`[no] redirect`

  Enable sending of ICMP redirect messages.

  no
    Disable sending of ICMP redirect messages
`[no] proxy-arp`

  Enable or disable Proxy ARP on this interface.

  When enabled the system will respond to ARP requests on behalf of other devices. The system will answer ARP requests for IP addresses that are not on this interface’s subnet, provided it has a route to reach those addresses via another interface.

  The system responds with its own MAC address, allowing it to act as a proxy for forwarding traffic between different subnets or networks.

  Default: Disabled

  no
    Disable proxy ARP on this interface
`[no] arp-notify`

  Enable or disable sending gratuitous ARP on this interface.

  When enabled the system will send gratuitous ARP frames when:

  - The interface is administratively brought up, i.e. it is enabled in the configuration.
  - The interface is operationally brought up.
  - The MAC address of the interface is changed.
  - The IP address of the interface is changed.

  Default: Enabled

  no
    Disable gratuitous ARP on this interface
`[no] arp-accept`

  Enable or disable accepting gratuitous ARP on this interface.

  When enabled the system will accept gratuitous ARP packets. If the ARP frame contain an IP address that is not present in the ARP table, the system will add the IP address to the ARP table. If the ARP frame contains an IP address that is already present in the ARP table, the ARP table will be updated with the new MAC address.

  Default: Enabled

  no
    Disable receiving gratuitous ARP on this interface
`[no] arp-watch`

  Enable ARP watch on this interface.

  When enabled the system will monitor ARP activity on this interface. These ARP events can be configured to be reported via:

  - audit: Log ARP events to the system audit log.
  - snmp: Generate SNMP Notifications (Traps/Informs) for ARP events.

  The following ARP events can be configured to be reported when/if they are detected on this interface:

  - new-station: The Ethernet address has not been seen before.
  - flip-flop: The Ethernet address changed from the most recently seen address to the second most recently seen address.
  - changed: The host switched to a new Ethernet address.
  - ethernet-broadcast: The MAC Ethernet address is a broadcast address.
  - ip-broadcast: The IP address is a broadcast address.
  - bogon: The source IP address is not local to the local subnet.
  - ethernet-mismatch: The source MAC Ethernet address didn’t match the address inside the ARP packet.
  - reused-address: The Ethernet address changed from the most recently seen address to the third (or greater) least recently seen address.
  - address-conflict: Indicates a possible IP address conflict based on MAC address changes observed in ARP traffic. Generated when any conflict related change event occurs (changed, flip-flop, or reused-address), providing a convenient way to detect potential address conflicts. Detection is based on stateless ARP frame observation and represents a potential conflict situation. This event is generated independently and will be reported even if the individual change events are disabled.

  When arp-watch is initially enabled, all events and all reporting methods are enabled by default, except address-conflict.

  Note

  The `arp-watch` command enters a sub-context that allows for configuration of which ARP events should be reported and how they should be reported.

  See ARP Watch Configuration below.

  Note

  For SNMP notifications to be generated, SNMP must be configured to send notifications. Enabling SNMP for ARP watch allows ARP watch events to generate SNMP notifications. However, if SNMP is not configured to send notifications, no notifications will be sent.

  See SNMP Configuration for more details on SNMP configuration.

  Default: Disabled

  Possible Routing performance impact

  Enabling this setting may have impact on routing performance, since it needs to inspect certain frames on this interface.

  Example:

      example:/config/iface-vlan1/#> arp-watch
      example:/config/iface-vlan1/#> no arp-watch
      example:/config/iface-vlan1/#> arp-watch report snmp audit
      example:/config/iface-vlan1/#> arp-watch no report snmp
      example:/config/iface-vlan1/#> arp-watch event bogon
      example:/config/iface-vlan1/#> no arp-watch event new-station

  no
    Disable ARP watch on this interface
`[no] ip-watch`

  Enable IP watch on this interface.

  When enabled the system will run IPwatchD tool to detect duplicate MAC/IP addresses on this interface. These events will be logged to the systems audit log. The following events are logged:

  - Duplicate IP Address: A remote device has the same IP as this interface.
  - Duplicate MAC Address: A remote device has the same MAC as this interface.

  Default: Disabled

  Possible Routing performance impact

  Enabling this setting may have impact on routing performance, since in needs to inspect certain frames on this interface.

  no
    Disable IP watch on this interface
`[no] name`

  This setting controls the interface name.

  no
    Default name used for this interface
`[no] distance [1-255] [track TRIGGER-ID]`

  Administrative distance for routes learned on this interface.

  Static routes learned dynamically, e.g. via DHCP, will be installed in the routing table with this administrative distance.

  Possible values are 1-255, where 1 is the best and 255 is infinity, it will be visible in the routing table but will never be activated.

  Use the form ‘no distance’ to reset the value to its default value, 16. Use ‘distance 255’ to prevent routes from ever being activated.

  A ping trigger can be associated with the interface distance setting. In case of connectivity loss, the distance of the associated route (s) are raised to infinity (255)

  no
    Use default distance for this interface (16)
`show`

  Show the summary for the configuration of the interface, an example is shown below.

      Name          : vlan1
      Admin Mode    : Up
      MAC Address   : AUTO
      IP Addresses  :
        Inet link-local
        Inet static
          192.168.2.10/24
      MTU           : AUTO (1500)
      ICMP Redirect : Sending
      Proxy ARP     : Disabled
      ARP Notify    : Enabled
      ARP Accept    : Enabled
      Distance      : 1

### Inet DHCP Configuration

DHCP client configuration is performed in a sub-context under the interface configuration:

    example:/config/iface-vlan1/#> inet dhcp
    example:/config/iface-vlan1/inet-dhcp/#>

`[no] clientid <hex|string> <STRING>`

  Configure the Client ID that is sent in DHCP requests.

  Default: Use mac address.

  no
    Remove the configured client-id and use the default value.
  hex
    Indicates that the subsequent value is provided in hexadecimal form. The following syntax forms are valid: `0x1a2b`, `1a:2b`, `1a2b`.
  string
    Indicates that the subsequent value is provided in string format.
`[no] arping`

  Enable ARP-ping option in DHCP client.

  no
    Disable ARP-ping option in DHCP client.

  Default: Enabled

`[no] option <OPT> [<OPT>...]`

  Configure the DHCP Parameter Request List (DHCP option 55) that the client provides in its communication with the server.

  The system supports the following options to be included in the DHCP Parameter Request List:

  Option Number | Description | Requested by Default
  --- | --- | ---
  1 | Subnet | Yes
  3 | Router | Yes
  6 | DNS Server | Yes
  7 | Log Server | Yes
  12 | Hostname | Yes
  15 | Domain | Yes
  42 | NTP Server | Yes
  66 | TFTP Server | -
  67 | Bootfile | -
  121 | Classless Route | Yes
  249 | Microsoft Classless Route | Yes

  Note

  Only the options that are explicitly requested will be used and applied on the device. In other words, if a DHCP server provides any of these options anyway, when it was not included as part of the client’s Parameter Request List, the client will ignore those options.

  WeOS handles DHCP options 12 and 15 in a special way. Currently, they are only used to add the hostname (option 12) along with any provided domain name (option 15) to the local DNS resolver configuration, which includes DNS host entries and search domains. They are not used in any other part of the system. To set the system hostname and domain name for other purposes, see the system settings documentation.

  DHCP Option 249 is a Microsoft specific variant of option 121. If both 121 and 249 are received as part of a lease, and their contents are identical, only one copy of the relevant routes will be installed on the client. If their content differ, their union will be installed. System administrators should ensure routes advertised by options 121 and 249 are identical.

  If DHCP Classless static route option (121 and/or 249) is configured on the WeOS DHCP client, then option 3 should also be configured. If the server provides option 121/249 in its response, it will be used by the client and any response to option 3 will be ignored.

  no

    Use `no option` to reset the option request to the default options. Use `no option OPT` to not request that specific option.

    Note

    If all specific option requests are removed no Parameter Request List will be included as part of the client’s requests, i.e. there is no implicit Parameter Request List (option 55) included from the client.

    In this scenario the DHCP client will apply any option it may support, if it is provided by the lease from the DHCP server.

  OPT
    DHCP option number.

### ARP Watch Configuration

ARP watch configuration is performed in a sub-context under the interface configuration:

    example:/config/iface-vlan1/#> arp-watch
    example:/config/iface-vlan1/arp-watch/#>

`[no] report [METHOD [ METHOD ...]]`

  Select how ARP watch events should be reported. Multiple reporting methods can be specified.

  Note

  If no specific method is specified, it is treated as `all`, which means that all methods are enabled or disabled together depending on whether ‘no’ is used or not.

  Default: All reporting methods are enabled when ARP watch is enabled.

  Example:

      example:/config/iface-vlan1/arp-watch/#> report snmp audit
      example:/config/iface-vlan1/arp-watch/#> no report snmp
      example:/config/iface-vlan1/arp-watch/#> no report
      example:/config/iface-vlan1/arp-watch/#> report all

  no
    Disable the specified reporting method(s), or all if none specified.
  METHOD

    The reporting method(s) to enable:

    - `audit`: Log ARP events to the system audit log.
    - `snmp`: Generate SNMP Notifications (Traps/Informs) for ARP events.
    - `all`: Enable all reporting methods.

    Note

    For SNMP notifications to be generated, SNMP must be configured to send notifications. Enabling SNMP for ARP watch allows ARP watch events to generate SNMP notifications. However, if SNMP is not configured to send notifications, no notifications will be sent.

    See SNMP Configuration for more details on SNMP configuration.

`[no] event [EVENT [ EVENT ...]]`

  Configure which ARP events should be monitored and reported. Multiple events can be specified.

  Note

  If no specific event is specified, it is treated as `all`, which means that all events are enabled or disabled together depending on whether ‘no’ is used or not.

  Default: All events are enabled when ARP watch is enabled.

  Example:

      example:/config/iface-vlan1/arp-watch/#> event new-station flip-flop changed
      example:/config/iface-vlan1/arp-watch/#> no event flip-flop
      example:/config/iface-vlan1/arp-watch/#> event flip-flop
      example:/config/iface-vlan1/arp-watch/#> no event
      example:/config/iface-vlan1/arp-watch/#> event all

  no
    Disable the specified event(s), or all if none specified.
  EVENT

    The event type(s) to enable:

    - `new-station`: The Ethernet address has not been seen before.
    - `flip-flop`: The Ethernet address changed from the most recently seen address to the second most recently seen address.
    - `changed`: The host switched to a new Ethernet address.
    - `ethernet-broadcast`: The MAC Ethernet address is a broadcast address.
    - `ip-broadcast`: The IP address is a broadcast address.
    - `bogon`: The source IP address is not local to the local subnet.
    - `ethernet-mismatch`: The source MAC Ethernet address didn’t match the address inside the ARP packet.
    - `reused-address`: The Ethernet address changed from the most recently seen address to the third (or greater) least recently seen address.
    - `address-conflict`: Indicates a possible IP address conflict based on MAC address changes observed in ARP traffic. Generated when any conflict- related change event occurs (changed, flip-flop, or reused-address), providing a convenient way to detect potential address conflicts. Detection is based on stateless ARP frame observation and represents a potential conflict situation. This event is generated independently and will be reported even if the individual change events are disabled.

## Examples

The factory configuration for a standard interface will be configured to acquire network address through DHCP and link-local address protocols. For the example below, we will configure the two host with static network addresses and link-local addresses also.

## Use case with static address

Two network units are connected via a network cable on port 1 on both hosts. Per default when a DHCP server isn’t present on the network the hosts will only acquire a link link address in the 169.254.0.0/16 range. In this case we want to set fixed addresses on both host in the 192.168.0.0/24 range. We’ll also use link local addresses on both hosts.

      Host-1                                          Host-2
     .-------.                                       .-------.
     |       |                                       |       |
     |       |                                       |       |
     |   1   |vlan1                             vlan1|   1   |
     '---+---'                                       '---+---'
         |.10                192.168.0.0/24           .20|
         +-----------------------------------------------+

`Configuration for Host-1`

      Host-1:/#> configure
      Host-1:/config/#> iface vlan1
      Host-1:/config/iface-vlan1/#> inet static 192.168.2.10/24
      Host-1:/config/iface-vlan1/inet-static-192.168.2.10/#> exit
      Host-1:/config/iface-vlan1/#> inet link-local
      Host-1:/config/iface-vlan1/inet-link-local#> leave

`Configuration for Host-2`

      Host-2:/#> configure
      Host-2:/config/#> iface vlan1
      Host-2:/config/iface-vlan1/#> inet static 192.168.2.20/24
      Host-2:/config/iface-vlan1/inet-static-192.168.2.20/#> exit
      Host-2:/config/iface-vlan1/#> inet link-local
      Host-2:/config/iface-vlan1/inet-link-local#> leave

## Use case in DHCP Client mode

Two network units are connected via a network cable on port 1 on both hosts. The Host-2 runs a DHCP server with subnet range 192.168.1.0. The DHCP-Server has in this case an address pool in the range of 192.168.1.100 and 192.168.1.199. The Host-1 is configured to use inet dhcp on vlan1. We’ll also use link local address.

      Host-1                                          Host-2
     .-------.                                       .-------.
     | DHCP  |                                       | DHCP  |
     | Client|                                       | Server|
     |   1   |vlan1                             vlan1|   1   |
     '---+---'                                       '---+---'
         | dhcp .100                192.168.1.0/24     .1|
         +-----------------------------------------------+
                                    pool 192.168.1.100-199

`Configuration for Host-1`

      Host-1:/#> configure
      Host-1:/config/#> iface vlan1
      Host-1:/config/iface-vlan1/#> inet dhcp
      Host-1:/config/iface-vlan1/inet-dhcp/#> exit
      Host-1:/config/iface-vlan1/#> inet link-local
      Host-1:/config/iface-vlan1/inet-link-local#> leave

`Configuration for Host-2`

      example:/#> configure
      example:/config/#> dhcp-server
      example:/config/dhcp-server/#> subnet 192.168.1.0/24
      Created new DHCP server for subnet 192.168.1.0.
      example:/config/dhcp-server/subnet-192.168.1.0/#>
      example:/config/dhcp-server/subnet-192.168.1.0/#>pool 192.168.1.50   192.168.1.99
      example:/config/dhcp-server/subnet-192.168.1.0/#>leave

for more information see * DHCP-Server/Configuration

### Status Overview

In order to verify an interface’s setting the ‘show’ command can be used:

    Host-1:/#> show iface vlan1
    Name         : vlan1
    Admin. State : Up
    Oper. Status : UP
    MAC Address  : 52:54:00:12:34:56
    IP Addresses : 192.168.2.10/24    (static)
                   169.254.81.131/16  (link-local)
    MTU          : 1500
    Statistics   :
                   RX: Packets    Bytes        Errors CsumErrs OutOfSeq Mcasts
                       57         4621         0      0        0        15
                   TX: Packets    Bytes        Errors DeadLoop NoRoute  NoBufs
                       164        29003        0      0        0        0

This show that the interface vlan1 on Host-1 is up. It has two network addresses, 192.168.2.10/24 which has been configured as static and also network address 169.254.81.131/16 which has been resolved through link-local addressing.

« Previous Next »