src/plugins/srv6-mobile/README.md

   1 SRv6 Mobile User Plane Plugin for VPP
   2 ========================
   3
   4 ## Introduction
   5
   6 This plugin module can provide the stateless mobile user plane protocols translation between GTP-U and SRv6.
   7 The functions of the translation take advantage of SRv6 network programmability.
   8 [SRv6 Mobile User Plane](https://tools.ietf.org/html/draft-ietf-dmm-srv6-mobile-uplane) defines the user plane protocol using SRv6
   9 including following stateless translation functions:
  10
  11 - **T.M.GTP4.D:**
  12    GTP-U over UDP/IPv4 -> SRv6
  13 - **End.M.GTP4.E:**
  14    SRv6 -> GTP-U over UDP/IPv4
  15 - **End.M.GTP6.D:**
  16    GTP-U over UDP/IPv6 -> SRv6
  17 - **End.M.GTP6.E:**
  18    SRv6 -> GTP-U over UDP/IPv6
  19
  20 These functions benefit user plane(overlay) to be able to utilize data plane(underlay) networks properly. And also it benefits
  21 data plane to be able to handle user plane in routing paradigm.
  22
  23 ## Getting started
  24 To play with SRv6 Mobile User Plane on VPP, you need to install following packages:
  25
  26         docker
  27         python3
  28         pip3
  29
  30         Python packages (use pip):
  31         docker
  32         scapy
  33         jinja2
  34
  35
  36 ### Quick-start
  37
  38 1. Build up the docker container image as following:
  39
  40 ```
  41 $ git clone https://github.com/filvarga/srv6-mobile.git
  42 $ cd ./srv6-mobile/extras/ietf105
  43 $ ./runner.py infra build
  44
  45 $ docker images
  46 REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
  47 ietf105-image       latest              577e786b7ec6        2 days ago          5.57GB
  48 ubuntu              18.04               4c108a37151f        4 weeks ago         64.2MB
  49
  50 ```
  51
  52 The runner script [runner.py](test/runner.py) has features to automate configurations and procedures for the test.
  53
  54 2. Instantiate test Scenario
  55
  56 Let's try following command to instantiate a topology:
  57
  58 ```
  59 $ ./runner.py infra start
  60 ```
  61
  62 This command instantiates 4 VPP containers with following topology:
  63
  64 ![Topology Diagram](test/topo-init.png)
  65
  66 You can check the instantiated docker instances with "docker ps".
  67
  68
  69 ```
  70 $ docker ps
  71 CONTAINER ID        IMAGE               COMMAND                  CREATED              STATUS              PORTS               NAMES
  72 44cb98994500        ietf105-image       "/bin/sh -c 'vpp -c …"   About a minute ago   Up About a minute                       hck-vpp-4
  73 6d65fff8aee9        ietf105-image       "/bin/sh -c 'vpp -c …"   About a minute ago   Up About a minute                       hck-vpp-3
  74 ad123b516b24        ietf105-image       "/bin/sh -c 'vpp -c …"   About a minute ago   Up About a minute                       hck-vpp-2
  75 5efed405b96a        ietf105-image       "/bin/sh -c 'vpp -c …"   About a minute ago   Up About a minute                       hck-vpp-1
  76
  77 ```
  78
  79 You can login to and configure each instantiated container.
  80
  81 ```
  82 $ ./runner.py cmd vppctl 0
  83
  84 Verified image: None
  85 connecting to: hck-vpp-1
  86     _______    _        _   _____  ___
  87  __/ __/ _ \  (_)__    | | / / _ \/ _ \
  88  _/ _// // / / / _ \   | |/ / ___/ ___/
  89  /_/ /____(_)_/\___/   |___/_/  /_/
  90
  91 vpp#
  92 ```
  93
  94 ## Test Scenarios
  95 ### SRv6 Drop-in between GTP-U tunnel
  96
  97 This test scenario introduces SRv6 path between GTP-U tunnel transparently. A GTP-U packet sent out from one end to another is translated to SRv6 and then back to GTP-U. All GTP-U tunnel identifiers are preserved in IPv6 header and SRH.
  98
  99
 100 #### GTP-U over UDP/IPv4 case
 101
 102 This case uses SRv6 end functions, T.M.GTP4.D and End.M.GTP4.E.
 103
 104 ![Topology Diagram](test/topo-test_gtp4d.png)
 105
 106 VPP1 is configured with "T.M.GTP4.D", and VPP4 is configured with "End.M.GTP4.E". Others are configured with "End". The packet generator sends a GTP-U packet over UDP/IPv4 toward the packet capture. VPP1 translates it to SRv6 toward D4::TEID with SR policy <D2::, D3::> in SRH. VPP4 translates the SRv6 packet to the original GTP-U packet and send out to the packet capture.
 107
 108 To start this case with IPv4 payload over GTP-U, you can run:
 109
 110 ```
 111 $ ./runner.py test tmap
 112 ```
 113
 114 If you want to use IPv6 payload instead of IPv4, you can run:
 115
 116 ```
 117 $ ./runner.py test tmap_ipv6
 118 ```
 119
 120
 121 #### GTP-U over UDP/IPv6 case
 122
 123 This case uses SRv6 end functions, End.M.GTP6.D.Di and End.M.GTP6.E.
 124
 125 ![Topology Diagram](test/topo-test_gtp6d.png)
 126
 127 VPP1 is configured with "End.M.GTP6.D.Di", and VPP4 is configured with "End.M.GTP4.E". Others are configured with "End". The packet generator sends a GTP-U packet over UDP/IPv6 toward D:: of the packet capture. VPP1 translates it to SRv6 toward D:: with SR policy <D2::, D3::, D4::TEID> in SRH. VPP4 translates the SRv6 packet to the original GTP-U packet and send out to the packet capture.
 128
 129 To start this case with IPv4 payload over GTP-U, you can run:
 130
 131 ```
 132 $ ./runner.py test gtp6_drop_in
 133 ```
 134
 135 If you want to use IPv6 payload instead of IPv4, you can run:
 136
 137 ```
 138 $ ./runner.py test gtp6_drop_in_ipv6
 139 ```
 140
 141
 142 ### GTP-U to SRv6
 143
 144 This test scenario demonstrates GTP-U to SRv6 translation. A GTP-U packet sent out from one end to another is translated to SRv6.
 145
 146 #### GTP-U over UDP/IPv6 case
 147
 148 ##### IPv4 payload
 149
 150 This case uses SRv6 end functions, End.M.GTP6.D and End.DT4.
 151
 152 ![Topology Diagram](test/topo-test_gtp6.png)
 153
 154 VPP1 is configured with "End.M.GTP6.D", and VPP4 is configured with "End.DT4". Others are configured with "End". The packet generator sends a GTP-U packet over UDP/IPv6 toward D::2. VPP1 translates it to SRv6 toward the IPv6 destination consists of D4:: and TEID of GTP-U with SR policy <D2::, D3::> in SRH. VPP4 decapsulates the SRv6 packet and lookup the table for the inner IPv4 packet and send out to the packet capture.
 155
 156 To start this case, you can run:
 157
 158 ```
 159 $ ./runner.py test gtp6
 160 ```
 161
 162 ##### IPv6 payload
 163
 164 This case uses SRv6 end functions, End.M.GTP6.D and End.DT6.
 165
 166
 167 ![Topology Diagram](test/topo-test_gtp6ip6.png)
 168
 169 The configurations are same with IPv4 payload case, except D4:: is configured as "End.DT6" in VPP4. VPP4 decapsulates the SRv6 packet and lookup the table for the inner IPv6 packet and send out to the packet capture.
 170
 171 If you want to use IPv6 payload instead of IPv4, you can run:
 172
 173 ```
 174 $ ./runner.py test gtp6_ipv6
 175 ```
 176
 177 ## More information
 178 TBD