GENEVE(4)

NAME
geneve - Generic Network Virtualization Encapsulation interface

SYNOPSIS
To compile this driver into the kernel, place the following line in your kernel configuration file:
device geneve

Alternatively, to load the driver as a module at boot time, place the following line in loader.conf(5):
if_geneve_load="YES"

DESCRIPTION
The geneve driver creates a generic network virtualization tunnel interfaces for Tentant Systems over an L3 (IP/UDP) underlay network that provides a Layer 2 (ethernet) or Layer 3 service using geneve protocol.

This driver corresponds to RFC 8926 for format specification and by default uses the multicast-learning-based approach for its control plane. To provide control plane independence all of the driver-specific operations are implemented using rtnetlink(4) and all the ioctl(2) calls are implemented using the nv(9) library. Each geneve interface is created at runtime using interface cloning. This is most easily done with the ifconfig(8) create command or using the cloned_interfaces variable in rc.conf(5). The interface may be removed with the ifconfig(8) destroy command.

The geneve interface must be configured in either L2 or L3 mode. An L2 geneve tunnel could be used as a backplane between the virtual switches residing in hypervisors, switches, or other appliances.

The L3 geneve tunnel provides virtualized IP forwarding service similar to IP/VRF.

By default the geneve driver creates an L2 interface that supports the usual network ioctl(2)s and thus can be used with ifconfig(8) like any other Ethernet interface. An L2 geneve interface encapsulates the Ethernet frame by prepending IP/UDP and geneve headers. Thus, the encapsulated (inner) frame is able to be transmitted over a routed, Layer 3 network to the remote host.

The geneve interface may be configured in either unicast or multicast mode. When in unicast mode, the interface creates a tunnel to a single remote host, and all traffic is transmitted to that host. When in multicast mode, the interface joins an IP multicast group, and receives packets sent to the group address, and transmits packets to either the multicast group address, or directly to the remote host if there is an appropriate forwarding table entry.

When the geneve interface is brought up, a udp(4) socket(9) is created based on the configuration, such as the local address for unicast mode or the group address for multicast mode, and the listening (local) port number. Since multiple geneve interfaces may be created that either use the same local address or join the same group address, and use the same port, the driver may share a socket among multiple interfaces. However, each interface within a socket must belong to a unique geneve segment per vnet(9). The analogous vlan(4) configuration would be a physical interface configured as the parent device for multiple VLAN interfaces, each with a unique VLAN tag. Each geneve segment is identified by a 24-bit value in the geneve header called the “Virtual Network Identifier”, or VNI. This value can be set with ifconfig(8) geneveid parameter.

When configured with the ifconfig(8) genevelearn parameter, the interface dynamically creates forwarding table entries from received packets. An entry in the forwarding table maps the inner source MAC address to the outer remote IP address. During transmit, the interface attempts to lookup an entry for the encapsulated destination MAC address. If an entry is found, the IP address in the entry is used to directly transmit the encapsulated frame to the destination. Otherwise, when configured in multicast mode, the interface must flood the frame to all hosts in the group. The maximum number of entries in the table is configurable with the ifconfig(8) genevemaxaddr command. Stale entries in the table are periodically pruned. The timeout is configurable with the ifconfig(8) genevetimeout command.

  MTU
Since the geneve interface encapsulates the Ethernet frame with an IP, UDP, and geneve header, the resulting frame may be larger than the MTU of the physical network. The geneve specification recommends the physical network MTU be configured to use jumbo frames to accommodate the encapsulated frame size.

By default, the geneve driver sets its MTU to usual ethernet MTU of 1500 bytes, reduced by the size of geneve headers prepended which is depends on genevemode.

Alternatively, the ifconfig(8) mtu command may be used to set the fixed MTU size on the geneve interface to allow the encapsulated frame to fit in the current MTU of the physical network. If the mtu command was used, system no longer adjust the geneve interface MTU on routing or address changes.

  Hop Limit
TTL value of geneve interface can change by using the ifconfig(8) genevettl command and it also can be inherited from carrying packet. You can set the genevettl to a number value or inherit option to be inherited at the encapsulation and decapsulation point.

  Traffic Class
Just like the TTL value, ToS value can be inherited at the encapsulation point using ifconfig(8) genevedscpinherit. As defined in RFC 8926, ECN value follows the RFC 6040 for both ingress and egress traffic.

  Don't Fragment
To make sure fragmentation does not happing during transmission, you can set the ifconfig(8) genevedf value to set value which sets the DF bit on IPv4 header and IP_DONTFRAG option on both IPv4 and IPv6 sockets. Similar to other options, it can be set to inherit value.

  Multicast
To create the geneve interface with multicast underlay, one must use ifconfig(8) genevegroup instead of geneveremote and set it to a multicast address (e.g. ff08::db8:0:1, 239.0.0.1). One can set the outbound multicast interface with ifconfig(8) genevedev to bound its multicast group to specific interface.

The ip_mroute kernel module for IPv4 underlay and ip6_mroute for IPv6 underlay must be loaded for multicast(4) to function.

HARDWARE
The geneve driver supports hardware checksum offload (receive and transmit) and TSO on the encapsulated traffic over physical interfaces that support these features. The geneve interface examines the genevedev interface, if one is specified, or the interface hosting the genevelocal address, and configures its capabilities based on the hardware offload capabilities of that physical interface. If multiple physical interfaces will transmit or receive traffic for the geneve then they all must have the same hardware capabilities. The transmit routine of a geneve interface may fail with ENXIO if an outbound physical interface does not support an offload that the geneve interface is requesting. This can happen if there are multiple physical interfaces involved, with different hardware capabilities, or an interface capability was disabled after the geneve interface had already started.

EXAMPLES

           Host A (198.51.100.10)
           +--------------------+
           | VNI 100 10.1.1.0/24|
           | VNI 200 10.2.2.0/24|
           +---------+----------+
                     |
             (198.51.100.0/24)
                     |
     +---------------v---------------+
     | Host B (203.0.113.1)          |
     |        +------+-------+       |
     | geneve0|              |geneve1|
     | +------v----+   +-----v-----+ |
     | | bridge0   |   | bridge1   | |
     | | (VNI 100) |   | (VNI 200) | |
     | +------+----+   +----+------+ |
     |        |             |        |
     +--------v-------------v--------+
       epair0b|             |epair1b
       +------+----+   +----+------+
       | Jail A    |   | Jail B    |
       | (10.1.1.x)|   | (10.2.2.x)|
       +-----------+   +-----------+

Assume host A has the (external) IP address 198.51.100.10 and two internal addresses of 10.1.1.1/24 and 10.2.2.1/24, while host B has the external address of 203.0.113.10 and two jails with their own separate VNET(9). the following commands will configure the tunnel:

On host A, create a l2 geneve interface in unicast mode:

    ifconfig geneve0 create geneveid 100 genevelocal 198.51.100.10 geneveremote 203.0.113.1
    ifconfig geneve1 create geneveid 200 genevelocal 198.51.100.10 geneveremote 203.0.113.1

On host B:

    ifconfig geneve0 create geneveid 100 genevelocal 203.0.113.1 geneveremote 198.51.100.10
    ifconfig geneve1 create geneveid 200 genevelocal 203.0.113.1 geneveremote 198.51.100.10
    ifconfig bridge0 addm geneve0 addm epair0a
    ifconfig bridge1 addm geneve1 addm epair1a

The example below demonstrate multicast configuration with IPv6:

                          ----------- VNI 42 -----------
                         /                              \
    2001:db8::1/64 --- Host A ------ Multicast ------- Host B --- 2001:db8::2/64
                      3fff::1 [em0] ff08::db8:1 [em0]  3fff::2

Create a geneve interface in multicast mode, with the genevelocal address of 3fff::1, and the genevegroup address of ff08::db8:0:1. The em0 interface will be used to transmit multicast packets. On host A:

    ifconfig geneve0 create geneveid 42 genevelocal 3fff::1 genevegroup ff08::db8:1 genevedev em0

On host B:

    ifconfig geneve0 create geneveid 42 genevelocal 3fff::2 genevegroup ff08::db8:1 genevedev em0

Once created, the geneve interface can be configured with ifconfig(8).

The following when placed in the file /etc/rc.conf will cause a geneve interface called “geneve0” to be created, and will configure the interface in unicast mode.

    cloned_interfaces="geneve0"
    create_args_geneve0="geneveid 108 genevelocal 192.168.100.1 geneveremote 192.168.100.2"

SEE ALSO
inet(4), inet6(4), multicast(4), rtnetlink(4), vlan(4), rc.conf(5), ifconfig(8), sysctl(8) J. Gross, Ed., I. Gross, Ed., T. Sridhar, Ed., Geneve: Generic Network Virtualization Encapsulation, November 2020, RFC 8926.

AUTHORS
-nosplit The geneve driver was written by Seyed Pouria Mousavizadeh Tehrani <info@spmzt.net>

BUGS
Current geneve implementation with netlink can't set geneve options other than genevemode during interface cloning in ifconfig without specifying the interface index.