aboutsummaryrefslogtreecommitdiffstats
path: root/src/plugins/cnat/cnat.rst
blob: a177bc10aa2e674e1d5097702e977fe6f0b3701d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
.. _dev_cnat:

.. toctree::

Cloud NAT
=========

Overview
________

This plugin covers specific NAT use-cases that come mostly
from the container networking world. On the contrary of the
NAT concepts used for e.g. a home gateway, there is no notion
of 'outside' and 'inside'. We handle Virtual (or Real) IPs and
translations of the packets destined to them

Terminology & Usage
___________________

Setting up the NAT will consist in the creation of a ``translation``
that has several backends. A ``translation`` is 3-tuple containing :
a fully qualified IP address a port and a protocol. All packets
destined to it (ip, port) will then choose one of the backends,
and follow its rewrite rules.

A ``backend`` consists of four rewrites components (source & destination
address, source & destination port) that shall be applied to packets
on the way in, and reverted on the way back.

Backends are equally load-balanced with a flow hash. The choice
of a ``backend`` for a flow will trigger the creation of a NAT ``session``,
that will store the packet rewrite to do and the one to undo
until the flow is reset or a timeout is reached

A ``session`` is a fully resolved 9-tuple of ``src_ip, src_port, dest_ip, dest_port, proto``
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.

These ``sessions`` expire after 30s for regular ``sessions`` and 1h for established
TCP connections. These can be changed in vpp's configuration file

.. code-block:: console

  cnat {
      session-max-age 60
      tcp-max-age 3600
  }

Traffic is matched by inserting FIB entries, that are represented
by a ``client``. These maintain a refcount of the number of ``sessions``
and/or ``translations`` depending on them and be cleaned up when
all have gone.

Translating Addresses
---------------------

In this example, all packets destined to ``30.0.0.2:80`` will be
rewritten so that their destination IP is ``20.0.0.1`` and destination
port ``8080``. Here ``30.0.0.2`` has to be a virtual IP, it cannot be
assigned to an interface

.. code-block:: console

  cnat translation add proto TCP vip 30.0.0.2 80 to ->20.0.0.1 8080


If ``30.0.0.2`` is the address of an interface, we can use the following
to do the same translation, and additionally change the source.
address with ``1.2.3.4``

.. code-block:: console

  cnat translation add proto TCP real 30.0.0.2 80 to 1.2.3.4->20.0.0.1 8080

To show existing translations and sessions you can use

.. code-block:: console

  show cnat session verbose
  show cnat translation


SourceNATing outgoing traffic
-----------------------------

A independent part of the plugin allows changing the source address
of outgoing traffic on a per-interface basis.

In the following example, all traffic coming from ``tap0`` and NOT
going to ``20.0.0.0/24`` will be source NAT-ed with ``30.0.0.1``.
On the way back the translation will be undone.

NB: ``30.0.0.1`` should be and address known to the FIB (e.g. the
address assigned to an interface)

.. code-block:: console

  set cnat snat-policy addr 30.0.0.1
  set cnat snat-policy if-pfx
  set cnat snat-policy if table include-v4 tap0
  set cnat snat-policy prefix 20.0.0.0/24
  set interface feature tap0 cnat-snat-ip4 arc ip4-unicast

To show the enforced snat policies:

.. code-block:: console

  show cnat snat-policy

Other parameters
----------------

In vpp's startup file, you can also configure the bihash sizes for

* the translation bihash ``(proto, port) -> translation``
* the session bihash ``src_ip, src_port, dest_ip, dest_port, proto -> new_src_ip, new_src_port, new_dest_ip, new_dest_port``
* the snat bihash for searching ``snat-policy`` excluded prefixes

.. code-block:: console

  cnat {
      translation-db-memory 64K
      translation-db-buckets 1024
      session-db-memory 1M
      session-db-buckets 1024
      snat-db-memory 64M
      snat-db-buckets 1024
  }

Extending the NAT
_________________

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 :

* Session lookup : ``rv`` will be set to ``0`` if a session was found
* Translation primitives ``cnat_translation_ip4`` based on sessions
* A session creation primitive ``cnat_session_create``

Creating a session will also create a reverse session (for matching return traffic),
and call a NAT node back that will perform the translation.

Known limitations
_________________

This plugin is still under development, it lacks the following features :
* Load balancing doesn't support parametric probabilities
* VRFs aren't supported. All rules apply to fib table 0 only
* Programmatic session handling (deletion, lifetime updates) aren't supported
* ICMP is not yet supported
* Traffic matching is only done based on ``(proto, dst_addr, dst_port)`` source matching isn't supported
* Statistics & session tracking are still rudimentary.