src/plugins/cnat/cnat.rst

   1 .. _dev_cnat:
   2
   3 .. toctree::
   4
   5 Cloud NAT
   6 =========
   7
   8 Overview
   9 ________
  10
  11 This plugin covers specific NAT use-cases that come mostly
  12 from the container networking world. On the contrary of the
  13 NAT concepts used for e.g. a home gateway, there is no notion
  14 of 'outside' and 'inside'. We handle Virtual (or Real) IPs and
  15 translations of the packets destined to them
  16
  17 Terminology & Usage
  18 ___________________
  19
  20 Setting up the NAT will consist in the creation of a ``translation``
  21 that has several backends. A ``translation`` is 3-tuple containing :
  22 a fully qualified IP address a port and a protocol. All packets
  23 destined to it (ip, port) will then choose one of the backends,
  24 and follow its rewrite rules.
  25
  26 A ``backend`` consists of four rewrites components (source & destination
  27 address, source & destination port) that shall be applied to packets
  28 on the way in, and reverted on the way back.
  29
  30 Backends are equally load-balanced with a flow hash. The choice
  31 of a ``backend`` for a flow will trigger the creation of a NAT ``session``,
  32 that will store the packet rewrite to do and the one to undo
  33 until the flow is reset or a timeout is reached
  34
  35 A ``session`` is a fully resolved 9-tuple of ``src_ip, src_port, dest_ip, dest_port, proto``
  36 to match incoming packets, and their new attributes ``new_src_ip, new_src_port, new_dest_ip, new_dest_port``. It allows for ``backend`` stickiness and a fast-path for established connections.
  37
  38 These ``sessions`` expire after 30s for regular ``sessions`` and 1h for established
  39 TCP connections. These can be changed in vpp's configuration file
  40
  41 .. code-block:: console
  42
  43   cnat {
  44       session-max-age 60
  45       tcp-max-age 3600
  46   }
  47
  48 Traffic is matched by inserting FIB entries, that are represented
  49 by a ``client``. These maintain a refcount of the number of ``sessions``
  50 and/or ``translations`` depending on them and be cleaned up when
  51 all have gone.
  52
  53 Translating Addresses
  54 ---------------------
  55
  56 In this example, all packets destined to ``30.0.0.2:80`` will be
  57 rewritten so that their destination IP is ``20.0.0.1`` and destination
  58 port ``8080``. Here ``30.0.0.2`` has to be a virtual IP, it cannot be
  59 assigned to an interface
  60
  61 .. code-block:: console
  62
  63   cnat translation add proto TCP vip 30.0.0.2 80 to ->20.0.0.1 8080
  64
  65
  66 If ``30.0.0.2`` is the address of an interface, we can use the following
  67 to do the same translation, and additionally change the source.
  68 address with ``1.2.3.4``
  69
  70 .. code-block:: console
  71
  72   cnat translation add proto TCP real 30.0.0.2 80 to 1.2.3.4->20.0.0.1 8080
  73
  74 To show existing translations and sessions you can use
  75
  76 .. code-block:: console
  77
  78   show cnat session verbose
  79   show cnat translation
  80
  81
  82 SourceNATing outgoing traffic
  83 -----------------------------
  84
  85 A independent part of the plugin allows changing the source address
  86 of outgoing traffic on a per-interface basis.
  87
  88 In the following example, all traffic coming from ``tap0`` and NOT
  89 going to ``20.0.0.0/24`` will be source NAT-ed with ``30.0.0.1``.
  90 On the way back the translation will be undone.
  91
  92 NB: ``30.0.0.1`` should be and address known to the FIB (e.g. the
  93 address assigned to an interface)
  94
  95 .. code-block:: console
  96
  97   set cnat snat-policy addr 30.0.0.1
  98   set cnat snat-policy if-pfx
  99   set cnat snat-policy if table include-v4 tap0
 100   set cnat snat-policy prefix 20.0.0.0/24
 101   set interface feature tap0 cnat-snat-ip4 arc ip4-unicast
 102
 103 To show the enforced snat policies:
 104
 105 .. code-block:: console
 106
 107   show cnat snat-policy
 108
 109 Other parameters
 110 ----------------
 111
 112 In vpp's startup file, you can also configure the bihash sizes for
 113
 114 * the translation bihash ``(proto, port) -> translation``
 115 * the session bihash ``src_ip, src_port, dest_ip, dest_port, proto -> new_src_ip, new_src_port, new_dest_ip, new_dest_port``
 116 * the snat bihash for searching ``snat-policy`` excluded prefixes
 117
 118 .. code-block:: console
 119
 120   cnat {
 121       translation-db-memory 64K
 122       translation-db-buckets 1024
 123       session-db-memory 1M
 124       session-db-buckets 1024
 125       snat-db-memory 64M
 126       snat-db-buckets 1024
 127   }
 128
 129 Extending the NAT
 130 _________________
 131
 132 This plugin is built to be extensible. For now two NAT types are defined, ``cnat_node_vip.c`` and ``cnat_node_snat.c``. They both inherit from ``cnat_node.h`` which provides :
 133
 134 * Session lookup : ``rv`` will be set to ``0`` if a session was found
 135 * Translation primitives ``cnat_translation_ip4`` based on sessions
 136 * A session creation primitive ``cnat_session_create``
 137 * A reverse session creation primitive ``cnat_rsession_create``
 138
 139 Creating a session will also create reverse session matching return traffic unless told otherwise by setting ``CNAT_TR_FLAG_NO_RETURN_SESSION`` on the translation. This will call the NAT nodes on the return flow and perform the inverse translation.
 140
 141 Known limitations
 142 _________________
 143
 144 This plugin is still under development, it lacks the following features :
 145 * Load balancing doesn't support parametric probabilities
 146 * VRFs are not supported, all rules apply regardless of the FIB table.
 147 * Programmatic session handling (deletion, lifetime updates) aren't supported
 148 * translations (i.e. rewriting the destination address) only match on the three
 149 tuple ``(proto, dst_addr, dst_port)`` other matches are not supported
 150 * Statistics & session tracking are still rudimentary.
 151
 152
 153
 154
 155