nat.proto

syntax = "proto3";

package ligato.vpp.nat;

option go_package = "go.ligato.io/vpp-agent/v3/proto/ligato/vpp/nat;vpp_nat";

// Nat44Global defines global NAT44 configuration.
// In VPP version 21.01 and newer the NAT44 plugin has to be explicitly enabled (by default it is
// disabled so that it doesn't consume any computational resources). With ligato control-plane
// the NAT44 plugin is enabled by submitting the NAT44Global configuration (even default values
// will make the plugin enabled). Without Nat44Global, all other NAT44 configuration items
// (DNat44, Nat44Interface and Nat44AddressPool) will be in the PENDING state.
message Nat44Global {
    // Enable/disable forwarding. By default it is disabled.
    bool forwarding = 1;
    // Enable/disable endpoint-independent mode.
    // In endpoint-independent (also known as "simple") mode the VPP NAT plugin holds
    // less information for each session, but only works with outbound NAT and static mappings.
    // In endpoint-dependent mode, which ligato selects as the default, the VPP NAT plugin uses
    // more information to track each session, which in turn enables additional features
    // such as out-to-in-only and twice-nat.
    // In older versions of VPP (<= 20.09) this field is ignored because mode at which the NAT44 plugin
    // operates is given by the VPP startup configuration file (i.e. config created before VPP even starts,
    // therefore not managed by ligato). The endpoint-independent mode is the default and the dependent mode
    // is turned on with this config stanza (included in vpp.conf used by ligato for older VPPs):
    //     nat {
    //         endpoint-dependent
    //     }
    bool endpoint_independent = 5;

    // Interface defines a network interface enabled for NAT.
    message Interface {
        // Interface name (logical).
        string name = 1;
        // Distinguish between inside/outside interface.
        bool is_inside = 2;
        // Enable/disable output feature.
        bool output_feature = 3;
    }
    // List of NAT-enabled interfaces. Deprecated - use separate Nat44Interface entries instead.
    repeated Interface nat_interfaces = 2 [deprecated=true];

    // Address defines an address to be used for source IP NAT.
    message Address {
        // IPv4 address.
        string address = 1;
        // VRF id of tenant, 0xFFFFFFFF means independent of VRF.
        // Non-zero (and not all-ones) VRF has to be explicitly created (see api/models/vpp/l3/vrf.proto).
        uint32 vrf_id = 2;
        // Enable/disable twice NAT.
        bool twice_nat = 3;
    }
    // Address pool used for source IP NAT. Deprecated - use separate Nat44AddressPool entries instead.
    repeated Address address_pool = 3 [deprecated=true];

    // Virtual reassembly for IPv4.
    VirtualReassembly virtual_reassembly = 4;
}

// DNat44 defines destination NAT44 configuration.
message DNat44 {
    // Unique identifier for the DNAT configuration.
    string label = 1;

    // Available protocols.
    enum Protocol {
        TCP = 0;
        UDP = 1;
        // ICMP is not permitted for load balanced entries.
        ICMP = 2;
    };

    // StaticMapping defines a list of static mappings in DNAT.
    message StaticMapping {
        // Interface to use external IP from; preferred over external_ip.
        string external_interface = 1;
        // External address.
        string external_ip = 2;
        // Port (do not set for address mapping).
        uint32 external_port = 3;

        // LocalIP defines a local IP addresses.
        message LocalIP {
            // VRF (table) ID. Non-zero VRF has to be explicitly created (see api/models/vpp/l3/vrf.proto).
            uint32 vrf_id = 1;
            // Local IP address).
            string local_ip = 2;
            // Port (do not set for address mapping).
            uint32 local_port = 3;
            // Probability level for load-balancing mode.
            uint32 probability = 4;
        }
        // List of local IP addresses. If there is more than one entry, load-balancing is enabled.
        repeated LocalIP local_ips = 4;

        // Protocol used for static mapping.
        Protocol protocol = 5;

        // Available twice-NAT modes.
        enum TwiceNatMode {
            DISABLED = 0;
            ENABLED = 1;
            SELF = 2;
        };
        // Enable/disable (self-)twice NAT.
        TwiceNatMode twice_nat = 6;

        // IP address from Twice-NAT address pool that should be used as source IP in twice-NAT processing.
        // This is override for default behaviour of choosing the first IP address from twice-NAT pool that
        // has available at least one free port (NAT is tracking translation sessions and exhausts free ports
        // for given IP address). This is needed for example in use cases when multiple twice-NAT
        // translations need to use different IP Addresses as source IP addresses.
        // This functionality works with VPP 20.09 and newer. It also needs to have twice_nat set to ENABLED.
        // It doesn't work for load-balanced static mappings (=local_ips has multiple values).
        string twice_nat_pool_ip = 8;

        // Session affinity. 0 means disabled, otherwise client IP affinity sticky time in seconds.
        uint32 session_affinity = 7;
    }
    // A list of static mappings in DNAT.
    repeated StaticMapping st_mappings = 2;

    // IdentityMapping defines an identity mapping in DNAT.
    message IdentityMapping {
        // VRF (table) ID. Non-zero VRF has to be explicitly created (see api/models/vpp/l3/vrf.proto).
        uint32 vrf_id = 1;
        // Name of the interface to use address from; preferred over ip_address.
        string interface = 2;
        // IP address.
        string ip_address = 3;
        // Port (do not set for address mapping).
        uint32 port = 4;
        // Protocol used for identity mapping.
        Protocol protocol = 5;

    }
    // A list of identity mappings in DNAT.
    repeated IdentityMapping id_mappings = 3;
}

// Nat44Interface defines a local network interfaces enabled for NAT44.
message Nat44Interface {
    // Interface name (logical).
    string name = 1;
    // Enable/disable NAT on inside.
    bool nat_inside = 2;
    // Enable/disable NAT on outside.
    bool nat_outside = 3;
    //  Enable/disable output feature.
    bool output_feature = 4;
}

// Nat44AddressPool defines an address pool used for NAT44.
message Nat44AddressPool {
    // Unique name for address pool
    string name = 5;
    // VRF id of tenant, 0xFFFFFFFF means independent of VRF.
    // Non-zero (and not all-ones) VRF has to be explicitly created (see api/models/vpp/l3/vrf.proto).
    uint32 vrf_id = 1;
    // First IP address of the pool.
    string first_ip = 2;
    // Last IP address of the pool. Should be higher than first_ip or empty.
    string last_ip = 3;
    // Enable/disable twice NAT.
    bool twice_nat = 4;
}

// VirtualReassembly defines NAT virtual reassembly settings.
message VirtualReassembly {
    // Reassembly timeout.
    uint32 timeout = 1;
    // Maximum number of concurrent reassemblies.
    uint32 max_reassemblies = 2;
    // Maximum number of fragments per reassembly.
    uint32 max_fragments = 3;
    // If set to true fragments are dropped, translated otherwise.
    bool drop_fragments = 4;
}