Documentation
VyOS Documentation
VyOS Interfaces
Pseudo-Ethernet (MACVLAN) Interfaces in VyOS

Pseudo-Ethernet (MACVLAN) Interfaces in VyOS

Pseudo-Ethernet, or MACVLAN, interfaces are virtual sub-interfaces of physical Ethernet interfaces, each with its own unique MAC address. This technology is especially useful in virtualized environments and for network testing.

Overview

What Is Pseudo-Ethernet (MACVLAN)

MACVLAN lets you create multiple virtual network interfaces on top of a single physical Ethernet port. Each virtual interface (sub-interface) gets its own unique MAC address and behaves like an independent physical interface.

Key features:

  • Each sub-interface has a unique MAC address
  • Lower system overhead compared to traditional bridging
  • Bypasses the 4096-VLAN-per-physical-port limit
  • Behaves like a real Ethernet interface
  • Supports IPv4 and IPv6 addressing
  • Inherits physical characteristics from the parent interface

Advantages

  1. Virtualization - ideal for virtual machines and containers
  2. Performance - low overhead, operates at the kernel level
  3. Scalability - create many logical interfaces without additional hardware
  4. Flexibility - work around network hardware limitations
  5. Testing - convenient for network testing and emulation

Limitations

Important limitations to keep in mind:

  1. Cannot ping from the host - Pseudo-Ethernet interfaces cannot be pinged from the host router itself
  2. No forwarding between Pseudo-Ethernet interfaces - Ethernet frames are not forwarded between MACVLAN interfaces on the same physical port
  3. Compatibility issues:
    • May not work in VMware ESXi (requires promiscuous mode)
    • Some network switches expect a single MAC per port and may block multiple MAC addresses
    • WiFi interfaces usually do not support multiple MAC addresses
  4. Security - some networks block ports with multiple MAC addresses for security reasons

Basic Configuration

Creating a Pseudo-Ethernet Interface

The core command for creating a MACVLAN interface:

# Create peth0 on top of eth0
set interfaces pseudo-ethernet peth0 source-interface eth0
set interfaces pseudo-ethernet peth0 address 192.0.2.1/24
set interfaces pseudo-ethernet peth0 description 'Pseudo-Ethernet on eth0'

commit
save

Configuration components:

  • peth0 - the virtual interface name (can be anything)
  • source-interface eth0 - the parent physical interface
  • address - the IP address of the virtual interface
  • description - the interface description

Multiple Pseudo-Ethernet Interfaces

Creating several MACVLAN interfaces on a single physical port:

# First pseudo-ethernet interface
set interfaces pseudo-ethernet peth0 source-interface eth0
set interfaces pseudo-ethernet peth0 address 10.10.0.1/24
set interfaces pseudo-ethernet peth0 description 'MACVLAN Interface 1'

# Second pseudo-ethernet interface
set interfaces pseudo-ethernet peth1 source-interface eth0
set interfaces pseudo-ethernet peth1 address 10.20.0.1/24
set interfaces pseudo-ethernet peth1 description 'MACVLAN Interface 2'

# Third pseudo-ethernet interface
set interfaces pseudo-ethernet peth2 source-interface eth0
set interfaces pseudo-ethernet peth2 address 10.30.0.1/24
set interfaces pseudo-ethernet peth2 description 'MACVLAN Interface 3'

commit
save

Verifying the Configuration

# Show all interfaces
show interfaces

# Show a specific pseudo-ethernet interface
show interfaces pseudo-ethernet peth0

# Detailed information
show interfaces pseudo-ethernet peth0 detail

# Statistics
show interfaces pseudo-ethernet peth0 statistics

# Brief information
show interfaces pseudo-ethernet peth0 brief

Parameter Configuration

IP Addressing

Static IPv4:

set interfaces pseudo-ethernet peth0 source-interface eth0
set interfaces pseudo-ethernet peth0 address 192.168.100.1/24
set interfaces pseudo-ethernet peth0 address 192.168.100.2/24

Static IPv6:

set interfaces pseudo-ethernet peth0 address 2001:db8:100::1/64
set interfaces pseudo-ethernet peth0 address 2001:db8:100::2/64

Dual-stack (IPv4 + IPv6):

set interfaces pseudo-ethernet peth0 source-interface eth0
set interfaces pseudo-ethernet peth0 address 192.168.100.1/24
set interfaces pseudo-ethernet peth0 address 2001:db8:100::1/64

DHCP Client

DHCPv4:

set interfaces pseudo-ethernet peth0 source-interface eth0
set interfaces pseudo-ethernet peth0 address dhcp
set interfaces pseudo-ethernet peth0 description 'DHCP client on peth0'

DHCPv6:

set interfaces pseudo-ethernet peth0 address dhcpv6

DHCP options:

# Client ID
set interfaces pseudo-ethernet peth0 dhcp-options client-id 'my-macvlan-client'

# Hostname
set interfaces pseudo-ethernet peth0 dhcp-options host-name 'vyos-macvlan'

# Vendor class ID
set interfaces pseudo-ethernet peth0 dhcp-options vendor-class-id 'vyos-peth'

# Default route distance
set interfaces pseudo-ethernet peth0 dhcp-options default-route-distance 210

# Reject the default route from DHCP
set interfaces pseudo-ethernet peth0 dhcp-options no-default-route

MAC Address

By default, a MACVLAN interface receives a randomly generated MAC address. You can assign a specific MAC:

# Set a specific MAC address
set interfaces pseudo-ethernet peth0 source-interface eth0
set interfaces pseudo-ethernet peth0 mac '00:50:56:00:ab:cd'
set interfaces pseudo-ethernet peth0 address 192.168.1.100/24

Note: Each MACVLAN interface must have a unique MAC address.

MTU (Maximum Transmission Unit)

# Set the MTU
set interfaces pseudo-ethernet peth0 source-interface eth0
set interfaces pseudo-ethernet peth0 mtu 1500
set interfaces pseudo-ethernet peth0 address 10.0.0.1/24

MTU recommendations:

  • The pseudo-ethernet MTU cannot exceed the parent interface MTU
  • Standard Ethernet: 1500
  • Jumbo frames: up to 9000 (requires physical interface support)

Interface Description

set interfaces pseudo-ethernet peth0 description 'Test network for lab environment'

Disabling the Interface

# Disable the interface
set interfaces pseudo-ethernet peth0 disable

# Enable the interface
delete interfaces pseudo-ethernet peth0 disable

Advanced Parameters

IPv4 Settings

ARP cache timeout:

set interfaces pseudo-ethernet peth0 ip arp-cache-timeout 3600

Proxy ARP:

set interfaces pseudo-ethernet peth0 ip enable-proxy-arp

Source validation (protection against IP spoofing):

# Strict mode (RFC 3704)
set interfaces pseudo-ethernet peth0 ip source-validation strict

# Loose mode
set interfaces pseudo-ethernet peth0 ip source-validation loose

# Disabled
set interfaces pseudo-ethernet peth0 ip source-validation disable

Disable IP forwarding on the interface:

set interfaces pseudo-ethernet peth0 ip disable-forwarding

IPv6 Settings

IPv6 autoconfiguration (SLAAC):

set interfaces pseudo-ethernet peth0 ipv6 address autoconf

Duplicate Address Detection (DAD):

set interfaces pseudo-ethernet peth0 ipv6 dup-addr-detect-transmits 1

Disable IPv6:

set interfaces pseudo-ethernet peth0 ipv6 disable

Disable IPv6 forwarding:

set interfaces pseudo-ethernet peth0 ipv6 disable-forwarding

VLAN on Pseudo-Ethernet

MACVLAN interfaces can have their own VLAN sub-interfaces:

# MACVLAN with VLAN tagging
set interfaces pseudo-ethernet peth0 source-interface eth0
set interfaces pseudo-ethernet peth0 vif 100 address 10.100.0.1/24
set interfaces pseudo-ethernet peth0 vif 100 description 'VLAN 100 on MACVLAN'

set interfaces pseudo-ethernet peth0 vif 200 address 10.200.0.1/24
set interfaces pseudo-ethernet peth0 vif 200 description 'VLAN 200 on MACVLAN'

commit

Structure:

eth0 (physical interface)
└── peth0 (MACVLAN)
    ├── peth0.100 (VLAN 100)
    └── peth0.200 (VLAN 200)

VRF (Virtual Routing and Forwarding)

Binding a Pseudo-Ethernet interface to a VRF:

# Create a VRF
set vrf name RED table 100

# Bind the pseudo-ethernet interface to the VRF
set interfaces pseudo-ethernet peth0 source-interface eth0
set interfaces pseudo-ethernet peth0 address 172.16.1.1/24
set interfaces pseudo-ethernet peth0 vrf RED

commit

Traffic Mirroring

# Mirror ingress traffic
set interfaces pseudo-ethernet peth0 mirror ingress eth1

# Mirror egress traffic
set interfaces pseudo-ethernet peth0 mirror egress eth1

Traffic Policies (QoS)

# Create a traffic policy
set traffic-policy shaper PETH-LIMIT bandwidth 100mbit
set traffic-policy shaper PETH-LIMIT default bandwidth 80mbit

# Apply it to the pseudo-ethernet interface
set interfaces pseudo-ethernet peth0 traffic-policy out PETH-LIMIT

Practical Use Cases

Scenario 1: Network Testing

Creating multiple test interfaces for a lab environment:

# Parent interface
set interfaces ethernet eth0 description 'Lab physical interface'

# Test network 1
set interfaces pseudo-ethernet lab1 source-interface eth0
set interfaces pseudo-ethernet lab1 address 10.1.1.1/24
set interfaces pseudo-ethernet lab1 description 'Lab Network 1'

# Test network 2
set interfaces pseudo-ethernet lab2 source-interface eth0
set interfaces pseudo-ethernet lab2 address 10.2.2.1/24
set interfaces pseudo-ethernet lab2 description 'Lab Network 2'

# Test network 3
set interfaces pseudo-ethernet lab3 source-interface eth0
set interfaces pseudo-ethernet lab3 address 10.3.3.1/24
set interfaces pseudo-ethernet lab3 description 'Lab Network 3'

# DHCP for each test network
set service dhcp-server shared-network-name LAB1 subnet 10.1.1.0/24 option default-router 10.1.1.1
set service dhcp-server shared-network-name LAB1 subnet 10.1.1.0/24 range 0 start 10.1.1.100
set service dhcp-server shared-network-name LAB1 subnet 10.1.1.0/24 range 0 stop 10.1.1.200

set service dhcp-server shared-network-name LAB2 subnet 10.2.2.0/24 option default-router 10.2.2.1
set service dhcp-server shared-network-name LAB2 subnet 10.2.2.0/24 range 0 start 10.2.2.100
set service dhcp-server shared-network-name LAB2 subnet 10.2.2.0/24 range 0 stop 10.2.2.200

commit
save

Scenario 2: Virtualization with Containers

Providing separate network interfaces for Docker or Podman containers:

# MACVLAN for container 1
set interfaces pseudo-ethernet container1 source-interface eth1
set interfaces pseudo-ethernet container1 address 172.20.1.2/24
set interfaces pseudo-ethernet container1 description 'Container 1 Network'

# MACVLAN for container 2
set interfaces pseudo-ethernet container2 source-interface eth1
set interfaces pseudo-ethernet container2 address 172.20.1.3/24
set interfaces pseudo-ethernet container2 description 'Container 2 Network'

# MACVLAN for container 3
set interfaces pseudo-ethernet container3 source-interface eth1
set interfaces pseudo-ethernet container3 address 172.20.1.4/24
set interfaces pseudo-ethernet container3 description 'Container 3 Network'

# Firewall isolation between containers
set firewall ipv4 forward filter rule 500 action drop
set firewall ipv4 forward filter rule 500 inbound-interface name container1
set firewall ipv4 forward filter rule 500 outbound-interface name container2

set firewall ipv4 forward filter rule 501 action drop
set firewall ipv4 forward filter rule 501 inbound-interface name container2
set firewall ipv4 forward filter rule 501 outbound-interface name container1

commit
save

Scenario 3: Multiple Subnets on a Single Port

Working around the limit on the number of VLANs per physical interface:

# Physical interface
set interfaces ethernet eth0 description 'Uplink to provider'

# Instead of using VLANs (which may be limited in number),
# we use MACVLAN interfaces

# Client 1 subnet
set interfaces pseudo-ethernet client1 source-interface eth0
set interfaces pseudo-ethernet client1 address 203.0.113.1/28
set interfaces pseudo-ethernet client1 description 'Client 1 subnet'

# Client 2 subnet
set interfaces pseudo-ethernet client2 source-interface eth0
set interfaces pseudo-ethernet client2 address 203.0.113.17/28
set interfaces pseudo-ethernet client2 description 'Client 2 subnet'

# Client 3 subnet
set interfaces pseudo-ethernet client3 source-interface eth0
set interfaces pseudo-ethernet client3 address 203.0.113.33/28
set interfaces pseudo-ethernet client3 description 'Client 3 subnet'

# NAT for each client
set nat source rule 100 outbound-interface name client1
set nat source rule 100 source address 10.0.1.0/24
set nat source rule 100 translation address 203.0.113.1

set nat source rule 110 outbound-interface name client2
set nat source rule 110 source address 10.0.2.0/24
set nat source rule 110 translation address 203.0.113.17

commit
save

Scenario 4: Network Performance Testing

Creating an environment for throughput testing:

# Source interface for generating traffic
set interfaces pseudo-ethernet perf-src source-interface eth0
set interfaces pseudo-ethernet perf-src address 192.168.50.1/24
set interfaces pseudo-ethernet perf-src description 'Performance test source'

# Destination interface for receiving traffic
set interfaces pseudo-ethernet perf-dst source-interface eth0
set interfaces pseudo-ethernet perf-dst address 192.168.50.2/24
set interfaces pseudo-ethernet perf-dst description 'Performance test destination'

# Allow traffic between the interfaces
set firewall ipv4 forward filter rule 600 action accept
set firewall ipv4 forward filter rule 600 source address 192.168.50.0/24
set firewall ipv4 forward filter rule 600 destination address 192.168.50.0/24

commit
save

# Testing with iperf3 (operational mode)
# On the destination:
run generate container image iperf3
run generate container name iperf-server image iperf3 network perf-dst command "-s"

# On the source:
run generate container name iperf-client image iperf3 network perf-src command "-c 192.168.50.2 -t 60"

Scenario 5: Separate Interfaces for Services

Splitting different services onto separate interfaces:

# MACVLAN for the DNS service
set interfaces pseudo-ethernet dns-service source-interface eth1
set interfaces pseudo-ethernet dns-service address 10.100.0.53/24
set interfaces pseudo-ethernet dns-service description 'DNS Service Interface'

# MACVLAN for the web service
set interfaces pseudo-ethernet web-service source-interface eth1
set interfaces pseudo-ethernet web-service address 10.100.0.80/24
set interfaces pseudo-ethernet web-service description 'Web Service Interface'

# MACVLAN for the mail service
set interfaces pseudo-ethernet mail-service source-interface eth1
set interfaces pseudo-ethernet mail-service address 10.100.0.25/24
set interfaces pseudo-ethernet mail-service description 'Mail Service Interface'

# Firewall: allow access to the services only on the required ports
set firewall ipv4 input filter rule 100 action accept
set firewall ipv4 input filter rule 100 destination address 10.100.0.53
set firewall ipv4 input filter rule 100 destination port 53
set firewall ipv4 input filter rule 100 protocol udp

set firewall ipv4 input filter rule 101 action accept
set firewall ipv4 input filter rule 101 destination address 10.100.0.80
set firewall ipv4 input filter rule 101 destination port 80,443
set firewall ipv4 input filter rule 101 protocol tcp

set firewall ipv4 input filter rule 102 action accept
set firewall ipv4 input filter rule 102 destination address 10.100.0.25
set firewall ipv4 input filter rule 102 destination port 25,587
set firewall ipv4 input filter rule 102 protocol tcp

commit
save

Integration with Cloud Platforms

Yandex Cloud

In Yandex Cloud, MACVLAN interfaces can be used to create additional IP addresses on a single virtual machine:

# Primary interface (assigned by Yandex Cloud)
# eth0: 10.128.0.10/24

# Additional IPs via MACVLAN
set interfaces pseudo-ethernet yc-web source-interface eth0
set interfaces pseudo-ethernet yc-web address 10.128.0.20/24
set interfaces pseudo-ethernet yc-web description 'Web service IP in Yandex Cloud'

set interfaces pseudo-ethernet yc-db source-interface eth0
set interfaces pseudo-ethernet yc-db address 10.128.0.21/24
set interfaces pseudo-ethernet yc-db description 'Database IP in Yandex Cloud'

# NAT for public access (if an external IP is available)
set nat destination rule 100 inbound-interface name eth0
set nat destination rule 100 destination port 80
set nat destination rule 100 protocol tcp
set nat destination rule 100 translation address 10.128.0.20
set nat destination rule 100 translation port 80

set nat destination rule 101 inbound-interface name eth0
set nat destination rule 101 destination port 3306
set nat destination rule 101 protocol tcp
set nat destination rule 101 translation address 10.128.0.21
set nat destination rule 101 translation port 3306

commit
save

Important for Yandex Cloud:

  • Make sure the security group allows traffic on the ports in use
  • When using multiple MAC addresses, check the network settings in the Yandex Cloud console
  • Some configurations may require enabling IP forwarding in the subnet settings

VK Cloud (Mail.ru Cloud)

A similar configuration for VK Cloud:

# Primary VK Cloud interface
# eth0: 10.0.1.10/24

# MACVLAN interfaces for microservices
set interfaces pseudo-ethernet vk-api source-interface eth0
set interfaces pseudo-ethernet vk-api address 10.0.1.20/24
set interfaces pseudo-ethernet vk-api description 'API Service - VK Cloud'

set interfaces pseudo-ethernet vk-frontend source-interface eth0
set interfaces pseudo-ethernet vk-frontend address 10.0.1.21/24
set interfaces pseudo-ethernet vk-frontend description 'Frontend - VK Cloud'

set interfaces pseudo-ethernet vk-backend source-interface eth0
set interfaces pseudo-ethernet vk-backend address 10.0.1.22/24
set interfaces pseudo-ethernet vk-backend description 'Backend - VK Cloud'

# Firewall for the microservice architecture
set firewall ipv4 forward filter rule 200 action accept
set firewall ipv4 forward filter rule 200 source address 10.0.1.21
set firewall ipv4 forward filter rule 200 destination address 10.0.1.20
set firewall ipv4 forward filter rule 200 destination port 8080
set firewall ipv4 forward filter rule 200 protocol tcp

commit
save

Monitoring and Diagnostics

Checking Interface Status

# List all pseudo-ethernet interfaces
show interfaces pseudo-ethernet

# A specific interface
show interfaces pseudo-ethernet peth0

# Detailed information
show interfaces pseudo-ethernet peth0 detail

# Brief information
show interfaces pseudo-ethernet peth0 brief

Interface Statistics

# Traffic statistics
show interfaces pseudo-ethernet peth0 statistics

# Packet counters
show interfaces pseudo-ethernet peth0 counters

# Reset the counters
clear interfaces pseudo-ethernet peth0 counters

MAC Addresses

# Show the interface MAC address
show interfaces pseudo-ethernet peth0 | grep "Hardware address"

# ARP table
show arp interface peth0

# In the operating system
ip link show peth0

Traffic Monitoring

# Real-time monitoring
monitor interfaces pseudo-ethernet peth0 traffic

# Traffic capture
monitor traffic interface peth0

# Filtered capture
monitor traffic interface peth0 filter 'port 80 or port 443'

# Save to a file
monitor traffic interface peth0 save /tmp/peth0-capture.pcap

Checking the Parent Interface

# Make sure the source interface is active
show interfaces ethernet eth0

# Physical state
show interfaces ethernet eth0 physical

# Verify the parent-child relationship
ip link show type macvlan

Troubleshooting

Interface Does Not Come Up

Problem: The pseudo-ethernet interface is in the down state.

Possible causes:

  1. The parent interface (source-interface) is in the down state
  2. Incorrect source-interface configuration
  3. MAC address conflict

Diagnostics:

# Check the state of the parent interface
show interfaces ethernet eth0

# Check the configuration
show configuration commands | grep pseudo-ethernet

# Check kernel messages
sudo dmesg | grep macvlan

# Check the state in the system
ip link show peth0

Solution:

# Make sure the parent interface is enabled
delete interfaces ethernet eth0 disable
commit

# Recreate the pseudo-ethernet interface
delete interfaces pseudo-ethernet peth0
commit

set interfaces pseudo-ethernet peth0 source-interface eth0
set interfaces pseudo-ethernet peth0 address 192.168.1.1/24
commit
save

No Network Connectivity

Problem: The interface is up, but there is no connectivity.

Possible causes:

  1. The switch blocks multiple MAC addresses on the port
  2. The firewall blocks the traffic
  3. Incorrect routing
  4. ARP issues

Diagnostics:

# Check ARP
show arp

# Check the routes
show ip route

# Ping with a source address
ping 192.168.1.100 source-address 192.168.1.1

# Check the firewall
show firewall

# tcpdump on the interface
sudo tcpdump -i peth0 -n

Solution for port security on the switch:

Cisco example:

interface GigabitEthernet0/1
 description VyOS with MACVLAN
 switchport mode access
 switchport access vlan 10
 spanning-tree portfast
 ! Allow multiple MAC addresses
 switchport port-security maximum 10
 switchport port-security

HP/Aruba example:

interface 1
 name "VyOS MACVLAN"
 untagged vlan 10
 ! Disable port security or increase the limit

MAC Address Conflict

Problem: Duplicate MAC addresses on the network.

Diagnostics:

# Show the MAC addresses of all interfaces
show interfaces | grep "Hardware address"

# Check in the system
ip link show | grep "link/ether"

# System log
show log | match "duplicate"

Solution:

# Assign a unique MAC manually
set interfaces pseudo-ethernet peth0 mac '00:50:56:01:23:45'
set interfaces pseudo-ethernet peth1 mac '00:50:56:01:23:46'
commit

Issues in a Virtualized Environment

Problem: MACVLAN does not work in VMware or another virtualized environment.

Cause: The virtual switch blocks multiple MAC addresses by default.

Solution for VMware:

  1. Enable promiscuous mode on the vSwitch:

    vSwitch -> Edit Settings -> Security
Promiscuous Mode: Accept
MAC Address Changes: Accept
Forged Transmits: Accept

  2. Or use a Port Group with the required settings:

    Port Group -> Security
Promiscuous Mode: Accept

Solution for KVM/QEMU:

<!-- Enable promiscuous mode in libvirt -->
<interface type='bridge'>
  <mac address='52:54:00:12:34:56'/>
  <source bridge='br0'/>
  <model type='virtio'/>
  <virtualport type='openvswitch'/>
  <!-- Allow multiple MACs -->
</interface>

Cannot Ping from the Router Itself

Problem: Pinging the pseudo-ethernet interface address from VyOS itself does not work.

Explanation: This is expected behavior for MACVLAN. From the documentation:

  • Pseudo-Ethernet interfaces cannot be pinged from the host system
  • Ethernet frames are not forwarded between MACVLAN interfaces on the same parent port

This is not a bug, but a characteristic of the MACVLAN architecture.

Workaround (if local connectivity is truly required):

# Use a bridge instead of MACVLAN
set interfaces bridge br0
set interfaces bridge br0 member interface eth0
set interfaces ethernet eth0 address 192.168.1.1/24

Performance Lower Than Expected

Problem: Low performance of the MACVLAN interfaces.

Diagnostics:

# Check error statistics
show interfaces pseudo-ethernet peth0 statistics

# Check CPU usage
show system resources

# Check the offload settings of the parent interface
ethtool -k eth0

Solution:

# Enable offload on the parent interface
set interfaces ethernet eth0 offload gro
set interfaces ethernet eth0 offload gso
set interfaces ethernet eth0 offload tso
commit

# Increase the ring buffer
set interfaces ethernet eth0 ring-buffer rx 1024
set interfaces ethernet eth0 ring-buffer tx 1024
commit

Operational Commands

Managing Interfaces

# Enable the interface
delete interfaces pseudo-ethernet peth0 disable
commit

# Disable the interface
set interfaces pseudo-ethernet peth0 disable
commit

# Delete the interface
delete interfaces pseudo-ethernet peth0
commit

Reset and Restart

# Reset the counters
clear interfaces pseudo-ethernet peth0 counters

# Restart the interface (down/up)
set interfaces pseudo-ethernet peth0 disable
commit
delete interfaces pseudo-ethernet peth0 disable
commit

Connectivity Testing

# Ping specifying a source
ping 192.168.1.100 source-address 192.168.1.1

# Traceroute with a source
traceroute 8.8.8.8 source-address 192.168.1.1

# Check the route
show ip route 192.168.1.0/24

Complete Configuration Examples

Example 1: Lab Environment with Multiple Networks

configure

# Physical interface
set interfaces ethernet eth0 description 'Physical uplink'
set interfaces ethernet eth0 address dhcp

# Lab network 1 - Development
set interfaces pseudo-ethernet dev-net source-interface eth1
set interfaces pseudo-ethernet dev-net address 10.10.1.1/24
set interfaces pseudo-ethernet dev-net description 'Development Network'

# Lab network 2 - Staging
set interfaces pseudo-ethernet stage-net source-interface eth1
set interfaces pseudo-ethernet stage-net address 10.10.2.1/24
set interfaces pseudo-ethernet stage-net description 'Staging Network'

# Lab network 3 - Production
set interfaces pseudo-ethernet prod-net source-interface eth1
set interfaces pseudo-ethernet prod-net address 10.10.3.1/24
set interfaces pseudo-ethernet prod-net description 'Production Network'

# DHCP for each network
set service dhcp-server shared-network-name DEV subnet 10.10.1.0/24 option default-router 10.10.1.1
set service dhcp-server shared-network-name DEV subnet 10.10.1.0/24 range 0 start 10.10.1.100
set service dhcp-server shared-network-name DEV subnet 10.10.1.0/24 range 0 stop 10.10.1.200

set service dhcp-server shared-network-name STAGE subnet 10.10.2.0/24 option default-router 10.10.2.1
set service dhcp-server shared-network-name STAGE subnet 10.10.2.0/24 range 0 start 10.10.2.100
set service dhcp-server shared-network-name STAGE subnet 10.10.2.0/24 range 0 stop 10.10.2.200

set service dhcp-server shared-network-name PROD subnet 10.10.3.0/24 option default-router 10.10.3.1
set service dhcp-server shared-network-name PROD subnet 10.10.3.0/24 range 0 start 10.10.3.100
set service dhcp-server shared-network-name PROD subnet 10.10.3.0/24 range 0 stop 10.10.3.200

# NAT for internet access
set nat source rule 100 outbound-interface name eth0
set nat source rule 100 source address 10.10.0.0/16
set nat source rule 100 translation address masquerade

# Firewall isolation
set firewall ipv4 forward filter rule 100 action accept
set firewall ipv4 forward filter rule 100 state established
set firewall ipv4 forward filter rule 100 state related

# Development → Internet (allowed)
set firewall ipv4 forward filter rule 110 action accept
set firewall ipv4 forward filter rule 110 source address 10.10.1.0/24
set firewall ipv4 forward filter rule 110 outbound-interface name eth0

# Staging → Internet (allowed)
set firewall ipv4 forward filter rule 120 action accept
set firewall ipv4 forward filter rule 120 source address 10.10.2.0/24
set firewall ipv4 forward filter rule 120 outbound-interface name eth0

# Production → Internet (allowed)
set firewall ipv4 forward filter rule 130 action accept
set firewall ipv4 forward filter rule 130 source address 10.10.3.0/24
set firewall ipv4 forward filter rule 130 outbound-interface name eth0

# Block traffic between environments
set firewall ipv4 forward filter rule 900 action drop
set firewall ipv4 forward filter rule 900 source address 10.10.1.0/24
set firewall ipv4 forward filter rule 900 destination address 10.10.2.0/24

set firewall ipv4 forward filter rule 901 action drop
set firewall ipv4 forward filter rule 901 source address 10.10.1.0/24
set firewall ipv4 forward filter rule 901 destination address 10.10.3.0/24

commit
save
exit

Example 2: Container Platform

configure

# Primary interface
set interfaces ethernet eth1 description 'Container network uplink'

# Container 1 - Web Frontend
set interfaces pseudo-ethernet cnt-web source-interface eth1
set interfaces pseudo-ethernet cnt-web address 172.20.1.10/24
set interfaces pseudo-ethernet cnt-web mac '02:00:00:00:01:10'
set interfaces pseudo-ethernet cnt-web description 'Web Frontend Container'

# Container 2 - Application Backend
set interfaces pseudo-ethernet cnt-app source-interface eth1
set interfaces pseudo-ethernet cnt-app address 172.20.1.20/24
set interfaces pseudo-ethernet cnt-app mac '02:00:00:00:01:20'
set interfaces pseudo-ethernet cnt-app description 'App Backend Container'

# Container 3 - Database
set interfaces pseudo-ethernet cnt-db source-interface eth1
set interfaces pseudo-ethernet cnt-db address 172.20.1.30/24
set interfaces pseudo-ethernet cnt-db mac '02:00:00:00:01:30'
set interfaces pseudo-ethernet cnt-db description 'Database Container'

# Container 4 - Cache (Redis)
set interfaces pseudo-ethernet cnt-cache source-interface eth1
set interfaces pseudo-ethernet cnt-cache address 172.20.1.40/24
set interfaces pseudo-ethernet cnt-cache mac '02:00:00:00:01:40'
set interfaces pseudo-ethernet cnt-cache description 'Cache Container'

# Firewall: microservice architecture
# Web → App (allowed)
set firewall ipv4 forward filter rule 200 action accept
set firewall ipv4 forward filter rule 200 source address 172.20.1.10
set firewall ipv4 forward filter rule 200 destination address 172.20.1.20
set firewall ipv4 forward filter rule 200 destination port 8080
set firewall ipv4 forward filter rule 200 protocol tcp

# App → Database (allowed)
set firewall ipv4 forward filter rule 201 action accept
set firewall ipv4 forward filter rule 201 source address 172.20.1.20
set firewall ipv4 forward filter rule 201 destination address 172.20.1.30
set firewall ipv4 forward filter rule 201 destination port 5432
set firewall ipv4 forward filter rule 201 protocol tcp

# App → Cache (allowed)
set firewall ipv4 forward filter rule 202 action accept
set firewall ipv4 forward filter rule 202 source address 172.20.1.20
set firewall ipv4 forward filter rule 202 destination address 172.20.1.40
set firewall ipv4 forward filter rule 202 destination port 6379
set firewall ipv4 forward filter rule 202 protocol tcp

# Web → Database (denied)
set firewall ipv4 forward filter rule 210 action drop
set firewall ipv4 forward filter rule 210 source address 172.20.1.10
set firewall ipv4 forward filter rule 210 destination address 172.20.1.30

commit
save
exit

Example 3: Multi-Tenant Environment

configure

# Physical interface
set interfaces ethernet eth2 description 'Multi-tenant uplink'

# Tenant 1
set interfaces pseudo-ethernet tenant1 source-interface eth2
set interfaces pseudo-ethernet tenant1 address 10.100.1.1/24
set interfaces pseudo-ethernet tenant1 mac '02:01:00:00:00:01'
set interfaces pseudo-ethernet tenant1 description 'Tenant 1 Network'

# Tenant 2
set interfaces pseudo-ethernet tenant2 source-interface eth2
set interfaces pseudo-ethernet tenant2 address 10.100.2.1/24
set interfaces pseudo-ethernet tenant2 mac '02:01:00:00:00:02'
set interfaces pseudo-ethernet tenant2 description 'Tenant 2 Network'

# Tenant 3
set interfaces pseudo-ethernet tenant3 source-interface eth2
set interfaces pseudo-ethernet tenant3 address 10.100.3.1/24
set interfaces pseudo-ethernet tenant3 mac '02:01:00:00:00:03'
set interfaces pseudo-ethernet tenant3 description 'Tenant 3 Network'

# VRF for each tenant (full isolation)
set vrf name TENANT1 table 101
set vrf name TENANT2 table 102
set vrf name TENANT3 table 103

set interfaces pseudo-ethernet tenant1 vrf TENANT1
set interfaces pseudo-ethernet tenant2 vrf TENANT2
set interfaces pseudo-ethernet tenant3 vrf TENANT3

# DHCP for each tenant
set service dhcp-server shared-network-name T1 subnet 10.100.1.0/24 option default-router 10.100.1.1
set service dhcp-server shared-network-name T1 subnet 10.100.1.0/24 range 0 start 10.100.1.100
set service dhcp-server shared-network-name T1 subnet 10.100.1.0/24 range 0 stop 10.100.1.200

set service dhcp-server shared-network-name T2 subnet 10.100.2.0/24 option default-router 10.100.2.1
set service dhcp-server shared-network-name T2 subnet 10.100.2.0/24 range 0 start 10.100.2.100
set service dhcp-server shared-network-name T2 subnet 10.100.2.0/24 range 0 stop 10.100.2.200

set service dhcp-server shared-network-name T3 subnet 10.100.3.0/24 option default-router 10.100.3.1
set service dhcp-server shared-network-name T3 subnet 10.100.3.0/24 range 0 start 10.100.3.100
set service dhcp-server shared-network-name T3 subnet 10.100.3.0/24 range 0 stop 10.100.3.200

# Bandwidth limiting for each tenant
set traffic-policy shaper TENANT1-LIMIT bandwidth 100mbit
set traffic-policy shaper TENANT2-LIMIT bandwidth 50mbit
set traffic-policy shaper TENANT3-LIMIT bandwidth 200mbit

set interfaces pseudo-ethernet tenant1 traffic-policy out TENANT1-LIMIT
set interfaces pseudo-ethernet tenant2 traffic-policy out TENANT2-LIMIT
set interfaces pseudo-ethernet tenant3 traffic-policy out TENANT3-LIMIT

commit
save
exit

Best Practices

  1. Planning:

    • Document the purpose of each MACVLAN interface
    • Use meaningful interface names (not just peth0, peth1)
    • Plan the MAC address scheme in advance

  2. MAC addresses:

    • Use MAC addresses from the locally administered range: they start with 02:, 06:, 0A:, 0E:
    • Avoid conflicts with existing MAC addresses on the network
    • Document the assigned MAC addresses

  3. Security:

    • Use a firewall to control traffic between MACVLAN interfaces
    • Apply source validation to prevent IP spoofing
    • Isolate critical services in separate VRFs

  4. Performance:

    • Enable hardware offload on the parent interface
    • Use jumbo frames if the network supports them
    • Monitor CPU usage and network throughput

  5. Compatibility:

    • Verify support for multiple MAC addresses on the switch
    • Enable promiscuous mode in virtualized environments
    • Test before deploying to production

  6. Monitoring:

    • Regularly check interface status
    • Monitor error statistics
    • Set up alerts for the down state

  7. Documentation:

    • Use description on all interfaces
    • Document the network topology
    • Maintain an inventory of MAC addresses

  8. Testing:

    • Always test in a lab environment
    • Verify connectivity after configuration
    • Test failover scenarios

  9. Limitations:

    • Remember that MACVLAN interfaces cannot be pinged from the router itself
    • Account for the lack of communication between MACVLAN interfaces on the same parent
    • Plan alternatives if local connectivity is required

  10. Backup:

    • Save the configuration regularly
    • Keep copies in a version control system
    • Document changes

Comparison with Alternatives

MACVLAN vs VLAN

CharacteristicMACVLANVLAN (802.1Q)
MAC addressesUnique per interfaceOne MAC, many VLANs
TaggingNot required802.1Q required
Switch supportMay require port security configurationStandard support
CountLimited by the MAC tableLimited to 4096 VLANs
Use caseVirtualization, testingNetwork segmentation
OverheadMinimal4 bytes per tag

MACVLAN vs Bridge

CharacteristicMACVLANBridge
PerformanceHigh (kernel level)Medium (STP overhead)
IsolationNo connectivity between sub-interfacesFull connectivity
Ping from the hostNot possiblePossible
Use caseIsolation, virtualizationCombining interfaces
ComplexitySimpleMedium

MACVLAN vs VRF

CharacteristicMACVLANVRF
Isolation levelL2 (MAC level)L3 (routing table)
RoutingShared table (unless VRF is used)Separate table
Use caseMultiple IPs on a single portMulti-tenancy routing
PerformanceHighMedium
CompatibilityMay be limitedBroad

Selection recommendations:

  • MACVLAN: virtualization, containers, testing, multiple IPs
  • VLAN: standard network segmentation, working with switches
  • Bridge: combining interfaces, connectivity between ports required
  • VRF: multi-tenancy, full isolation of routing tables

Conclusion

Pseudo-Ethernet (MACVLAN) interfaces in VyOS provide a powerful and flexible mechanism for creating multiple virtual interfaces on top of a single physical port. They are especially useful in the following scenarios:

  • Virtualization and containers - providing isolated network interfaces
  • Testing - creating lab environments without additional hardware
  • Working around limitations - operating on networks where VLANs are limited
  • Microservices - isolating services with separate IP addresses
  • Multi-tenancy - splitting network resources between clients

When using MACVLAN, it is important to keep the limitations in mind:

  • The inability to ping from the host system
  • The lack of communication between MACVLAN interfaces on the same parent
  • Possible compatibility issues with some network hardware

Proper planning, configuration, and monitoring of MACVLAN interfaces let you make effective use of this technology across various network scenarios, providing flexibility and performance with minimal overhead.

Next Steps

Reviewed by OpenNix LLC · Last updated on
Loopback Interfaces in VyOSVXLAN Interfaces in VyOS