go.ligato.io/vpp-agent/v3@v3.5.0/proto/ligato/vpp/interfaces/interface.proto

syntax = "proto3";

package ligato.vpp.interfaces;

option go_package = "go.ligato.io/vpp-agent/v3/proto/ligato/vpp/interfaces;vpp_interfaces";

import "ligato/vpp/ipsec/ipsec.proto";
import "ligato/annotations.proto";

// Interface defines a VPP interface.
message Interface {
    // Name is mandatory field representing logical name for the interface.
    // It must be unique across all configured VPP interfaces.
    string name = 1;

    // Type defines VPP interface types.
    enum Type {
        UNDEFINED_TYPE = 0;
        SUB_INTERFACE = 1;
        SOFTWARE_LOOPBACK = 2;
        DPDK = 3;
        MEMIF = 4;
        TAP = 5;
        AF_PACKET = 6;
        VXLAN_TUNNEL = 7;
        IPSEC_TUNNEL = 8 [deprecated=true]; // Deprecated in VPP 20.01+. Use IPIP_TUNNEL + ipsec.TunnelProtection instead.
        VMXNET3_INTERFACE = 9;
        BOND_INTERFACE = 10;
        GRE_TUNNEL = 11;
        GTPU_TUNNEL = 12;
        IPIP_TUNNEL = 13;
        WIREGUARD_TUNNEL = 14;
        RDMA = 15;
    };
    // Type represents the type of VPP interface and it must match the actual Link.
    Type type = 2;

    // Enabled controls if the interface should be UP.
    bool enabled = 3;

    // PhysAddress represents physical address (MAC) of the interface.
    // Random address will be assigned if left empty.
    string phys_address = 4;

    // IPAddresses define list of IP addresses for the interface and must be
    // defined in the following format: <ipAddress>/<ipPrefix>.
    // Interface IP address can be also allocated via netalloc plugin and
    // referenced here, see: api/models/netalloc/netalloc.proto
    repeated string ip_addresses = 5  [(ligato_options).type = IP_WITH_MASK];

    // Vrf defines the ID of VRF table that the interface is assigned to.
    // The VRF table must be explicitely configured (see api/models/vpp/l3/vrf.proto).
    // When using unnumbered interface the actual vrf is inherited from
    // the interface referenced by the numbered interface and this field is ignored.
    uint32 vrf = 6;

    // SetDhcpClient enables DHCP client on interface.
    bool set_dhcp_client = 7;

    // Ip6Nd is used to enable/disable IPv6 ND address autoconfiguration
    // and setting up default routes
    message IP6ND {
        // Enable IPv6 ND address autoconfiguration.
        bool address_autoconfig = 1;
        // Enable installing default routes.
        bool install_default_routes = 2;
    }
    IP6ND ip6_nd = 14;

    // Mtu sets MTU (Maximum Transmission Unit) for this interface.
    // If set to zero, default MTU (usually 9216) will be used.
    uint32 mtu = 8  [(ligato_options).int_range = {minimum: 0 maximum: 9216}];

    // Unnumbered is used for inheriting IP address from another interface.
    message Unnumbered {
        // InterfaceWithIp is the name of interface to inherit IP address from.
        string interface_with_ip = 1;
    }
    Unnumbered unnumbered = 9;

    message RxMode {
        uint32 queue = 1;

        // Type definition is from: vpp/include/vnet/interface.h
        enum Type {
            UNKNOWN = 0;
            POLLING = 1;
            INTERRUPT = 2;
            ADAPTIVE = 3;
            DEFAULT = 4;
        };
        Type mode = 2;

        // DefaultMode, if set to true, the <queue> field will be ignored
        // and the <mode> will be used as a default for all the queues.
        bool default_mode = 3;
    }
    repeated RxMode rx_modes = 12;

    message RxPlacement {
        // Select from interval <0, number-of-queues)
        uint32 queue = 1;
        // Select from interval <0, number-of-workers)
        uint32 worker = 2;
        // Let the main thread to process the given queue
        //  - if enabled, value of <worker> is ignored
        bool main_thread = 3;
    }
    repeated RxPlacement rx_placements = 13;

    // Link defines configuration for specific interface types.
    // It can be nil for some interfaces types like: loopback and DPDK.
    oneof link {
        SubInterface sub = 100;
        MemifLink memif = 101;
        AfpacketLink afpacket = 102;
        TapLink tap = 103;
        VxlanLink vxlan = 104;
        IPSecLink ipsec = 105 [deprecated=true]; // Deprecated in VPP 20.01+. Use IPIP_TUNNEL + ipsec.TunnelProtection instead.
        VmxNet3Link vmx_net3 = 106;
        BondLink bond = 107;
        GreLink gre = 108;
        GtpuLink gtpu = 109;
        IPIPLink ipip = 110;
        WireguardLink wireguard = 111;
        RDMALink rdma = 112;
    };
};

// SubInterface defines configuration for interface type: SUB_INTERFACE
message SubInterface {
    // Name of the parent (super) interface
    string parent_name = 1;
    // SubInterface ID, used as VLAN
    uint32 sub_id = 2;

    enum TagRewriteOptions {
        DISABLED = 0;
        PUSH1 = 1;
        PUSH2 = 2;
        POP1 = 3;
        POP2 = 4;
        TRANSLATE11 = 5;
        TRANSLATE12 = 6;
        TRANSLATE21 = 7;
        TRANSLATE22 = 8;
    }
    // VLAN tag rewrite rule applied for given tag for sub-interface
    TagRewriteOptions tag_rw_option = 3;
    // Set ether-type of the first tag to dot1q if true, dot1ad otherwise
    bool push_dot1q = 4;
    // First tag (required for PUSH1 and any TRANSLATE)
    uint32 tag1 = 5;
    // Second tag (required for PUSH2 and any TRANSLATE)
    uint32 tag2 = 6;
}

// MemifLink defines configuration for interface type: MEMIF
message MemifLink {
    enum MemifMode {
        ETHERNET = 0;
        IP = 1;
        PUNT_INJECT = 2;
    }
    MemifMode mode = 1;

    bool master = 2;
    // Id is a 32bit integer used to authenticate and match opposite sides of the connection
    uint32 id = 3;
    // Filename of the socket used for connection establishment
    string socket_filename = 4;
    string secret = 5;
    // The number of entries of RX/TX rings
    uint32 ring_size = 6;
    // Size of the buffer allocated for each ring entry
    uint32 buffer_size = 7;
    // Number of rx queues (only valid for slave)
    uint32 rx_queues = 8;
    // Number of tx queues (only valid for slave)
    uint32 tx_queues = 9;
}

// VxlanLink defines configuration for interface type: VXLAN_TUNNEL
message VxlanLink {
    // SrcAddress is source VTEP address
    string src_address = 1  [(ligato_options).type = IP];
    // DstAddress is destination VTEP address
    string dst_address = 2  [(ligato_options).type = IP];
    // Vni stands for VXLAN Network Identifier 
    uint32 vni = 3;     
    // Multicast defines name of multicast interface     
    string multicast = 4;    

    // Gpe (Generic Protocol Extension) allows encapsulating not only Ethernet frame payload.
    message Gpe {
        uint32 decap_vrf_id = 1;
        enum Protocol {
            UNKNOWN = 0;
            IP4 = 1;
            IP6 = 2;
            ETHERNET = 3;
            NSH = 4;
        };
        // Protocol defines encapsulated protocol
        Protocol protocol = 2;
    }
    Gpe gpe = 5;
}

// AfpacketLink defines configuration for interface type: AF_PACKET
message AfpacketLink {
    // Name of the host (Linux) interface to bind to.
    // This type of reference is suitable for scenarios when the target interface
    // is not managed (and should not be touched) by the agent. In such cases the interface
    // does not have logical name in the agent's namespace and can only be referenced
    // by the host interface name (i.e. the name used in the Linux network stack).
    // Please note that agent learns about externally created interfaces through netlink
    // notifications.
    // If, however, the target interface is managed by the agent, then it is recommended
    // to use the alternative reference <linux_interface> (see below), pointing to the interface
    // by its logical name. One advantage of such approach is, that if AF-PACKET and the target
    // Linux interface are requested to be created at the same time, then it can be done inside
    // the same transaction because the agent does not rely on any notification from the Linux.
    // It is mandatory to define either <host_if_name> or <linux_interface>.
    string host_if_name = 1;

    // Logical name of the Linux interface to bind to.
    // This is an alternative interface reference to <host_if_name> and preferred
    // if the target interface is managed by the agent and not created externally
    // (see comments for <host_if_name> for explanation).
    // It is mandatory to define either <host_if_name> or <linux_interface>.
    string linux_interface = 2;
}

// TapLink defines configuration for interface type: TAP
message TapLink {
    // 1 / unset = use the original TAP interface; 2 = use a fast virtio-based TAP
    uint32 version = 1;     
    // Name of the TAP interface in the host OS;
    // if empty, it will be auto-generated (suitable for combination with TAP_TO_VPP
    // interface from Linux ifplugin, because then this name is only temporary anyway)
    string host_if_name = 2;
    // If TAP connects VPP with microservice, fill this parameter with the target
    // microservice name - should match with the namespace reference of the associated
    // TAP_TO_VPP interface (it is still moved to the namespace by Linux-ifplugin but
    // VPP-ifplugin needs to be aware of this dependency)
    string to_microservice = 3; 
    // Rx ring buffer size; must be power of 2; default is 256; only for TAP v.2
    uint32 rx_ring_size = 4;
    // Tx ring buffer size; must be power of 2; default is 256; only for TAP v.2
    uint32 tx_ring_size = 5;
    // EnableGso enables GSO mode for TAP interface.
    bool enable_gso = 6;
    // EnableTunnel enables tunnel mode for TAP interface.
    bool enable_tunnel = 7;
}

// IPSecLink defines configuration for interface type: IPSEC_TUNNEL
// In VPP 21.06 and newer, IPSecLink serves just for creation of the link and thus only tunnel_mode is taken into
// account and all of the remaining (deprecated) fields are ignored.
// Please use separate SecurityPolicy, SecurityAssociation and TunnelProtection messages from ligato.vpp.ipsec
// package to associate SA, SP and tunnel protection with the link.
message IPSecLink {
    enum Mode {
        // point-to-point tunnel
        POINT_TO_POINT = 0;
        // point-to multipoint tunnel (supported starting from VPP 20.05)
        POINT_TO_MULTIPOINT = 1;
    };
    // Mode of the IPIP tunnel
    Mode tunnel_mode = 1;

    // Extended sequence number
    bool esn = 2 [deprecated=true];
    // Anti replay option
    bool anti_replay = 3 [deprecated=true];
    // Local IP address
    string local_ip = 4  [(ligato_options).type = IP, deprecated=true];
    // Remote IP address
    string remote_ip = 5  [(ligato_options).type = IP, deprecated=true];
    // Local security parameter index
    uint32 local_spi = 6 [deprecated=true];
    // Remote security parameter index
    uint32 remote_spi = 7 [deprecated=true];

    // Cryptographic algorithm for encryption
    ipsec.CryptoAlg crypto_alg = 8 [deprecated=true];
    string local_crypto_key = 9 [deprecated=true];
    string remote_crypto_key = 10 [deprecated=true];

    // Cryptographic algorithm for authentication
    ipsec.IntegAlg integ_alg = 11 [deprecated=true];
    string local_integ_key = 12 [deprecated=true];
    string remote_integ_key = 13 [deprecated=true];

    bool enable_udp_encap = 14 [deprecated=true];
}

// VmxNet3Link defines configuration for interface type: VMXNET3_INTERFACE
// PCI address (unsigned 32bit int) is derived from vmxnet3 interface name. It is expected that the interface
// name is in format `vmxnet3-<d>/<b>/<s>/<f>`, where `d` stands for domain (max ffff), `b` is bus (max ff),
// `s` is slot (max 1f) and `f` is function (max 7). All values are base 16
message VmxNet3Link {
    // Turn on elog
    bool enable_elog = 2;
    // Receive queue size (default is 1024)
    uint32 rxq_size = 3;
    // Transmit queue size (default is 1024)
    uint32 txq_size = 4;
}

// BondLink defines configuration for interface type: BOND_INTERFACE
message BondLink {
    uint32 id = 1;

    enum Mode {
      UNKNOWN = 0;
      ROUND_ROBIN = 1;
      ACTIVE_BACKUP = 2;
      XOR = 3;
      BROADCAST = 4;
      LACP = 5;
    }
    Mode mode = 3;

    enum LoadBalance {
        L2 = 0;
        L34 = 1;
        L23 = 2;
        // Round robin
        RR = 3;
        // Broadcast
        BC = 4;
        // Active backup
        AB = 5;
    }
    // Load balance is optional and valid only for XOR and LACP modes
    LoadBalance lb = 4;

    message BondedInterface {
        string name = 1;
        bool is_passive = 2;
        bool is_long_timeout = 3;
    }
    repeated BondedInterface bonded_interfaces = 12;
}

message GreLink {
    enum Type {
        UNKNOWN = 0;
        // L3 GRE (i.e. this tunnel is in L3 mode)
        L3 = 1; 
        // TEB - Transparent Ethernet Bridging - the tunnel is in L2 mode
        TEB = 2; 
        // ERSPAN - the tunnel is for port mirror SPAN output
        ERSPAN = 3; 
    };
    Type tunnel_type = 1;

    string src_addr = 2  [(ligato_options).type = IP];
    string dst_addr = 3  [(ligato_options).type = IP];

    uint32 outer_fib_id = 4;
    uint32 session_id = 5;
}

message GtpuLink {
    enum NextNode {
        // The default next node is l2-input
        DEFAULT = 0;
        // l2-input
        L2 = 1;
        // ip4-input
        IP4 = 2;
        // ip6-input
        IP6 = 3;
    };
    // Source VTEP address
    string src_addr = 1  [(ligato_options).type = IP];
    // Destination VTEP address
    string dst_addr = 2  [(ligato_options).type = IP];
    // Name of multicast interface
    string multicast = 3;
    // Tunnel endpoint identifier - local
    uint32 teid = 4;
    // Tunnel endpoint identifier - remote
    uint32 remote_teid = 7;
    // VRF id for the encapsulated packets
    uint32 encap_vrf_id = 5;
    // DEPRECATED - use decap_next_node
    NextNode decap_next = 6 [deprecated=true];
    // Next VPP node after decapsulation
    uint32 decap_next_node = 8;
}

message IPIPLink {
    enum Mode {
        // point-to-point tunnel
        POINT_TO_POINT = 0;
        // point-to multipoint tunnel (supported starting from VPP 20.05)
        POINT_TO_MULTIPOINT = 1;
    };
    // Mode of the IPIP tunnel
    Mode tunnel_mode = 1;

    // Source VTEP IP address
    string src_addr = 2  [(ligato_options).type = IP];
    // Destination VTEP IP address
    string dst_addr = 3  [(ligato_options).type = IP];
}

message WireguardLink {
  // Private-key base64
  string private_key = 2;

  // Listen UDP port
  uint32 port = 3  [(ligato_options).int_range = {minimum: 0 maximum: 65535}];

  // Source IP address
  string src_addr = 4  [(ligato_options).type = IP];
}

// https://github.com/FDio/vpp/blob/master/src/plugins/rdma/rdma_doc.rst
message RDMALink {
    enum Mode {
        AUTO = 0;
        // InfiniBand Verb (using libibverb).
        IBV = 1;
        // Direct Verb allows the driver to access the NIC HW RX/TX rings directly
        // instead of having to go through libibverb and suffering associated overhead.
        // It will be automatically selected if the adapter supports it.
        DV = 2;
    };

    // Linux interface name representing the RDMA-enabled network device to attach into.
    string host_if_name = 1;

    // Mode at which the RDMA driver operates.
    Mode mode = 2;

    // Number of receive queues.
    // By default only one RX queue is used.
    uint32 rxq_num = 3;

    // The size of each RX queue.
    // Default is 1024 bytes.
    uint32 rxq_size = 4;

    // The size of each TX queue.
    // Default is 1024 bytes.
    uint32 txq_size = 5;
}