summaryrefslogtreecommitdiffstats
path: root/src/plugins/nat/nat44-ed/nat44_ed_doc.rst
blob: a54531c688ceac6be7212d8fd40fac601bc3faef (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
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
.. _NAT44_Endpoint_Dependent:

.. toctree::

NAT44-ED: NAT44 Endpoint Dependent
==================================

Introduction
------------

NAT44-ED is the IPv4 endpoint dependent network address translation
plugin. The component implements an address and port-dependent mapping
and address and port-dependent filtering NAT as described in
`RFC4787 <https://tools.ietf.org/html/rfc4787>`__.

The outside address and port (X1’:x1’) is reused for internal hosts
(X:x) for different values of Y:y. A flow is matched by {source address,
destination address, protocol, transport source port, transport
destination port, fib index}. As long as all these are unique the
mapping is valid. While a single outside address in theory allows for
2^16 source ports \* 2^32 destination IP addresses \* 2^16 destination
ports = 2^64 sessions, this number is much smaller in practice. Few
destination ports are generally used (80, 443) and a fraction of the IP
address space is available. The limitation is 2^16 bindings per outside
IP address to a single destination address and port (Y:y).

The implementation is split, a control-plane / slow-path and a
data-plane / fast-path. Essentially acting as a flow router. The
data-plane does a 6-tuple flow lookup (SA, DA, P, SP, DP, FIB) and on a
match runs the per-flow packet handling instructions on the packet. On a
flow lookup miss, the packet is punted to the slow-path, where depending
on policy new sessions are created.

The support set of packet handling instructions is ever-increasing.
Currently, the implementation supports rewrite of SA, DA, SP, DP and TCP
MSS. The fast-path also does connection tracking and expiry of older
sessions.

NAT44-ED uses 6
tuple\ ``(src address, src port, dst address, dst port, protocol and fib)``\ for
matching communication.

Structure
~~~~~~~~~

1) Dynamic NAT

-  also called PAT (Port Address Translation)
-  supports port overloading

2) Static NAT

-  types of Static NAT:

   a) identity mapping

   -  exceptions to translations

   b) static mapping

   -  supported features:

      1. address only mapping

      -  one to one translation without ports

      2. twice-nat

      -  double-nat, translation of source and destination

      3. self-twice-nat

      -  double nat, translation of source and destination, where
         external host address is the same as local host address

      4. out2in-only mapping

      -  session is created only from outside interface (out2in feature)

   c) load balanced static mapping

   -  translates one frontend (``addr``:``port``) to multiple backends
      (``addr``:``port``)

3) Interfaces

a) inside interface (in2out feature) - local to external network
   translation - feature is before ip4-lookup
b) outside interface (out2in feature) - external to local network
   translation - feature is before ip4-lookup
c) inside & outside interface (classify feature) - local or external
   network translation - correct type of translation is determined per
   communication - feature is before ip4-lookup
d) output interface (output feature) - used for post routing translation
   - feature is after ip4-lookup

4) Addresses

a) interface address - automatically managed external address - first
   address of VPP interface
b) pool address - range of external addresses

5) Logging and Accounting

a) ipfix logging
b) syslog

6) Miscellaneous Features

a) inter-vrf translation control 1. basic

   -  nat44 plugin enable inside-vrf / outside-vrf
   -  inside/outside interface vrf’s

      2. advanced

   -  vrf table routing feature

b) udp/tcp/icmp timeouts - configurable timeouts for these protocols
c) session limiting 1. basic (plugin enable [sessions ] 2. advanced
   (per vrf table / global limiting)
d) mss-clamping - MSS (maximum segment size) is by default determined by
   egress interface MTU (maximum transmission unit) size - used to lower
   MSS value in VPN tunnel scenarios where additional headers can
   enlarge the packet beyond MTU causing drops
e) hairpinning - hosts on the same lan segment communicating via
   external address
f) forwarding - if enabled translation only occurs if active session or
   static configuration exist, rest of the traffic is passed without
   being translated

Session Table
-------------

Session table exists per thread and contains pool of sessions that can
be either expired or not expired. NAT44-ED plugin doesn’t use scavenging
for clearing expired sessions. Rather then using scavenging plugin uses
LRU doubly-linked list. LRU contains ordered list of sessions indices.
Head of the list contains last updated session. Each session holds
record of the LRU head (tcp transitory, tcp established, udp, icmp or
unknown lru head). Because of this plugin can reach maximum number of
sessions without requirement to clear old sessions. During session
creation if a maximum number of sessions was reached LRU head is
checked. Expired head record gets deleted and a new session gets
created. For better performance LRU head records exist. Each time a new
packet is received session index gets moved to the tail of LRU list.

Terminology
-----------

IN2OUT (inside to outside translation) OUT2IN (outside to inside
translation)

NAT (network address translation) PAT (port address translation) MSS
(maximum segment size) MTU (maximum transmission unit) VRF (virtual
routing and forwarding)

HAIRPINNING

Dynamic NAT (Minimal Required Configuration)
--------------------------------------------

::

       +-------------+
       | 10.0.0.0/24 |
       +-------------+
              |
   +----------------------+
   | GigabitEthernet0/8/0 |
   +----------------------+
   +----------------------+
   | GigabitEthernet0/a/0 |
   +----------------------+
              |
       +-------------+
       | 10.0.1.0/24 |
       +-------------+

1) enable nat plugin

..

   nat44 enable sessions 10000

2) configure NAT interfaces, two options:

a) add inside NAT interface on local VPP interface, add outside NAT
   interface on external VPP interface

..

   set interface nat44 in GigabitEthernet0/8/0 out GigabitEthernet0/a/0

b) add output NAT interface on external VPP interface

..

   set interface nat44 in GigabitEthernet0/a/0 output-feature

3) configure NAT address

a) add external address range

..

   nat44 add address 10.0.1.1

b) add external VPP interface address

..

   nat44 add interface address GigabitEthernet0/a/0

Static NAT
----------

Identity Mapping
~~~~~~~~~~~~~~~~

   nat44 add identity mapping ``ip4-addr``\ \|external ``interface``
   [``protocol`` ``port``] [vrf ``table-id``] [del]

Static Mapping
~~~~~~~~~~~~~~

   nat44 add static mapping tcp|udp|icmp local ``addr``
   [``port|icmp-echo-id``] external ``addr`` [``port|icmp-echo-id``]
   [vrf ``table-id``] [twice-nat|self-twice-nat] [out2in-only] [exact
   ``pool-addr``] [del]

Load Balanced Static Mapping
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   nat44 add load-balancing back-end protocol tcp|udp external
   ``addr``:``port`` local ``addr``:``port`` [vrf ``table-id``]
   probability ``n`` [del]

..

   nat44 add load-balancing static mapping protocol tcp|udp external
   ``addr``:``port`` local ``addr``:``port`` [vrf ``table-id``]
   probability ``n`` [twice-nat|self-twice-nat] [out2in-only] [affinity
   ``timeout-seconds``] [del]

Interfaces
----------

Inside Interface
~~~~~~~~~~~~~~~~

::

        NAT INSIDE IF
   +----------------------+
   | GigabitEthernet0/8/0 |
   +----------------------+

..

   set interface nat44 in GigabitEthernet0/8/0 [del]

NAT inside interface is used for translating local to external
communication. Translates Dynamic and Static NAT traffic. If no matching
session is found a new session is created for both Dynamic NAT and
Static NAT. Dynamic NAT sessions can get created only on inside
interface.

Outside Interface
~~~~~~~~~~~~~~~~~

::

        NAT OUTSIDE IF
   +----------------------+
   | GigabitEthernet0/a/0 |
   +----------------------+

..

   set interface nat44 out GigabitEthernet0/a/0 [del]

NAT outside interface is used for translating external to local
communication. Translates Dynamic and Static NAT traffic. New session
gets created only if no matching session is found and matching Static
NAT configuration exists.

Inside & Outside Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~

::

       NAT IN AND OUT IF
   +----------------------+
   | GigabitEthernet0/8/0 |
   +----------------------+
       NAT IN AND OUT IF
   +----------------------+
   | GigabitEthernet0/a/0 |
   +----------------------+

..

   set interface nat44 in GigabitEthernet0/8/0 out GigabitEthernet0/8/0
   [del]

   set interface nat44 in GigabitEthernet0/a/0 out GigabitEthernet0/a/0
   [del]

If one VPP interface is configured both as inside and outside NAT
interface then classification feature is used. By default NAT inside
interface uses in2out feature and NAT outside uses out2in feature.
Classification feature determines if the communication should be passed
to in2out feature or to out2in feature. Traffic will get passed to
out2in feature if destination address is one of NAT addresses or a
static mapping in out2in direction flow matches this communication. By
default all traffic is passed to in2out feature.

Output Interface
~~~~~~~~~~~~~~~~

::

       +-------------+          +-------------+
       | 10.0.2.0/24 |          | 10.0.3.0/24 |
       +-------------+          +-------------+
              |                        |
   +----------------------+ +----------------------+
   | GigabitEthernet0/7/0 | | GigabitEthernet0/8/0 |
   +----------------------+ +----------------------+
                     NAT OUTPUT IF
               +----------------------+
               | GigabitEthernet0/a/0 |
               +----------------------+
                      +----------+
                      | 10.0.1.1 |
                      +----------+
                           |
                     +-------------+
                     | 10.0.1.0/24 |
                     +-------------+

..

   set interface nat44 in GigabitEthernet0/a/0 output-feature [del]

NAT output interface acts as both inside and outside interfaces. Inside
rules apply for all egress communication on VPP interface and outside
rules apply for all ingress communication. Compared to inside/outside
NAT configuration method non of the local interfaces require to be
configured as inside NAT interfaces. Translation only occurs after
routing decision has been made and just before leaving NAT output
interface. In above example all traffic destined for 10.0.1.0/24 from
10.0.2.0/24 or 10.0.3.0/24 will get translated. NAT output interface
acts as post-routing feature.

Addresses
---------

Interface Address
~~~~~~~~~~~~~~~~~

   nat44 add interface address ``interface`` `twice-nat <#twice-nat>`__
   [del]

NAT interface address is a standard external pool address that gets auto
added upon resolving first VPP interface address. Supports both standard
address and twice-nat address. Twice-nat address is used in conjunction
with static mapping twice-nat and self-twice-nat feature.

Pool Address
~~~~~~~~~~~~

   nat44 add address ``ip4-range-start`` [- ``ip4-range-end``]
   [tenant-vrf ``vrf-id``] `twice-nat <#twice-nat>`__ [del]

Statically configured address or range of addresses that supports both
standard and twice-nat address. Specifying vrf-id lets user assign
address/addresses to specific NAT inside interfaces that belong to the
same vrf table.

Logging
-------

   nat set logging level ``level``

Configuration of logging level is used only for internal VPP logging.

   nat ipfix logging [domain ``domain-id``] [src-port ``port``]
   [disable]

Both syslog and ipfix support connection tracking capabilities. Session
creation, session deletion, maximum sessions exceeded among other things
are logged by syslog and ipfix.

Miscellaneous
-------------

VRFs
~~~~

::

            VRF 0                    VRF 1
       +-------------+          +-------------+
       | 10.0.2.0/24 |          | 10.0.3.0/24 |
       +-------------+          +-------------+
              |                        |
        NAT INSIDE IF            NAT INSIDE IF
   +----------------------+  +----------------------+
   | GigabitEthernet0/7/0 |  | GigabitEthernet0/8/0 |
   +----------------------+  +----------------------+
        NAT OUTSIDE IF           NAT OUTSIDE IF
   +----------------------+  +----------------------+
   | GigabitEthernet0/a/0 |  | GigabitEthernet0/b/0 |
   +----------------------+  +----------------------+
            VRF 2                      VRF 3
              |                          |
              +--------------------------+
                           |
        +------------+------------+------------+
        |            |            |            |
   +----------+ +----------+ +----------+ +----------+
   | 10.0.0.1 | | 10.0.0.2 | | 10.0.1.1 | | 10.0.1.2 |
   +----------+ +----------+ +----------+ +----------+
    VRF 0 POOL   VRF 1 POOL   VRF 0 POOL   VRF 1 POOL

..

   nat44 add address ``ip4-addr`` [tenant-vrf ``vrf-id``] [del]

   nat44 plugin enable inside-vrf ``vrf-id`` outside-vrf ``vrf-id``
   [disable]",

Default behavior
^^^^^^^^^^^^^^^^

By design NAT supports passing communication between VRFs. Passing
communication between multiple different VRFs is also supported (GE0/7/0
-> GE0/b/0, GE0/8/0 -> GE0/a/0).

NAT pool address tenant-vrf configuration parameter is used to constrain
pool address to specific inside VRF. Example communication (in the above
diagram): 1) from GE0/7/0 -> GE0/b/0 would choose 10.0.1.1 pool address
2) from GE0/8/0 -> GE0/b/0 would choose 10.0.1.2 pool address

Plugin enable parameters inside-vrf and outside-vrf are used as follows:

Both ``inside-vrf`` and ``outside-vrf`` configuration parameters are
used in conjunction with Static NAT, inside-vrf is only used for Static
NAT.

inside VRF: - used only in conjunction with static mappings - default
inside VRF parameter is used in in2out feature to lookup static mapping
if mapping can’t be found by inside interface VRF - used as default when
adding static mappings as in2out vrf

outside VRF: - used in conjunction with static mappings - secondary
option for looking up static mappings in in2out feature based on outside
VRF - used as default destination vrf in in2out feature during session
creation if non of outside interfaces can resolve destination IP address

Session creation default behavior (in2out only): - ingress interface fib
is used as inside fib - Outside fib is chosen based on ability to
resolve destination address in one of the outside interface networks. if
there is no such network that is able to resolve destination a default
outside fib (outside vrf index) is used.

Default behavior enables use of multiple outside and inside fibs with
some limitations. The limitation in the default behavior is that if each
interface belonging to different fib contains default gateway every time
first interface network fib gets used as outside fib index during
session creation.

VRF tables
^^^^^^^^^^

   nat44 vrf table [add|del] ``vrf-id``

..

   nat44 vrf route [add|del] table ``vrf-id`` ``vrf-id``

VRF tables change the default behavior of working with inter-vrf
communication. Adding empty VRF table disables passing communication
between VRFs. Adding additional routes to the table makes destination
VRF decision making algorithm do lookups into these tables. During
session creation destination VRF in in2out feature is resolved by
traversing VRF routes in the matching VRF table. If VRF route resolves
destination IPv4 address then this VRF gets used. If non VRF route can
resolve destination IPv4 address If VRF route can’t be found source VRF
will be used. Priority of VRF routes is based on order of configuration.

Timeouts
~~~~~~~~

   set nat timeout [udp ``sec`` \| tcp-established ``sec``
   tcp-transitory ``sec`` \| icmp ``sec`` \| reset]

Session Limiting
~~~~~~~~~~~~~~~~

   nat44 enable sessions ``max-number``

Maximum number of sessions value is used on per-thread (per-worker)
basis.

   set nat44 session limit ``limit`` [vrf ``table-id``]

Per-vrf session limiting makes it possible to split maximum number of
sessions between different VRFs.

MSS Clamping
~~~~~~~~~~~~

   nat mss-clamping ``mss-value``\ \|disable

Forwarding
~~~~~~~~~~

   nat44 forwarding enable|disable

Additional Configuration Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   | set nat frame-queue-nelts ``number``
   | set nat workers ``workers-list``
   | nat44 del session in|out ``addr``:``port`` tcp|udp|icmp [vrf
     ``id``] [external-host ``addr``:``port``]

Show commands
^^^^^^^^^^^^^

::

   show nat workers
   show nat timeouts
   show nat44 summary
   show nat44 sessions
   show nat44 addresses
   show nat mss-clamping
   show nat44 interfaces
   show nat44 vrf tables
   show nat44 hash tables
   nat44 show static mappings
   show nat44 interface address

Configuration Examples
----------------------

TWICE-NAT
~~~~~~~~~

Twice NAT lets you translate both the source and destination address in
a single rule. Currently, twice NAT44 is supported only for local
network service session initiated from outside network. Twice NAT static
mappings can only get initiated (create sessions) from outside network.

Topology
^^^^^^^^

::

   +--------------------------+
   | 10.0.0.2/24 (local host) |
   +--------------------------+
               |
   +---------------------------------+
   | 10.0.0.1/24 (eth0) (nat inside) |
   | 20.0.0.1/24 (eth1) (nat outside)|
   +---------------------------------+
               |
   +---------------------------+
   | 20.0.0.2/24 (remote host) |
   +---------------------------+

In this example traffic will be initiated from remote host. Remote host
will be accessing local host via twice-nat mapping.

Translation will occur as follows:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

outside to inside translation:


   | src address: 20.0.0.2 -> 192.168.160.101
   | dst address: 20.0.0.1 -> 10.0.0.2

inside to outside translation:


   | src address: 10.0.0.2 -> 20.0.0.1
   | dst address: 192.168.160.101 -> 20.0.0.2

Configuration
^^^^^^^^^^^^^

Enable nat44-ed plugin:


::

   nat44 enable sessions 1000

Configure inside interface:


::

   set int state eth0 up
   set int ip address eth0 10.0.0.1/24
   set int nat44 in eth0

Configure outside interface:


::

   set int state eth1 up
   set int ip address eth1 20.0.0.1/24
   set int nat44 out eth1

Configure nat address pools:


::

   nat44 add address 20.0.0.1
   nat44 add address 192.168.160.101 twice-nat

-  alternatively we could use ``nat44 add interface address eth1``
-  both pools are required
-  pool ``20.0.0.1`` is used for out2in incoming traffic
-  special twice-nat pool ``192.168.160.101`` is used for secondary
   translation

Finally, add twice-nat mapping:


   nat44 add static mapping tcp local 10.0.0.2 5201 external 20.0.0.1
   5201 twice-nat

SELF TWICE-NAT
~~~~~~~~~~~~~~

Self twice NAT works similar to twice NAT with few exceptions. Self
twice NAT is a feature that lets client and service running on the same
host to communicate via NAT device. This means that external address is
the same address as local address. Self twice NAT static mappings can
only get initiated (create sessions) from outside network.

.. _topology-self-twice-nat:

Topology
^^^^^^^^

::

   +--------------------------+
   | 10.0.0.2/24 (local host) |
   +--------------------------+
               |
   +-------------------------------------------+
   | 10.0.0.1/24 (eth0) (nat inside & outside) |
   +-------------------------------------------+

In this example traffic will be initiated from local host. Local host
will be accessing itself via self-twice-nat mapping.

.. _translation-will-occur-as-follows-1:

Translation will occur as follows:
''''''''''''''''''''''''''''''''''

.. _outside-to-inside-translation-1:

outside to inside translation:


   | src address: 10.0.0.2 -> 192.168.160.101
   | dst address: 10.0.0.1 -> 10.0.0.2

.. _inside-to-outside-translation-1:

inside to outside translation:


   | src address: 10.0.0.2 -> 10.0.0.1
   | dst address: 192.168.160.101 -> 10.0.0.2

.. _configuration-1:

Configuration
^^^^^^^^^^^^^

.. _enable-nat44-ed-plugin-1:

Enable nat44-ed plugin:


::

   nat44 enable sessions 1000

Configure NAT interface:


::

   set int state eth0 up
   set int ip address eth0 10.0.0.1/24
   set int nat44 in eth0
   set int nat44 out eth0

.. _configure-nat-address-pools-1:

Configure nat address pools:


::

   nat44 add address 10.0.0.1
   nat44 add address 192.168.160.101 twice-nat

Finally, add self-twice-nat mapping:


   nat44 add static mapping tcp local 10.0.0.2 5201 external 10.0.0.1
   5201 self-twice-nat