]>
Commit | Line | Data |
---|---|---|
6b702a45 QY |
1 | .. _zebra: |
2 | ||
3 | ***** | |
4 | Zebra | |
5 | ***** | |
42fc5d26 | 6 | |
6b702a45 | 7 | .. _zebra-protocol: |
42fc5d26 QY |
8 | |
9 | Overview of the Zebra Protocol | |
10 | ============================== | |
718e3744 | 11 | |
4e0b5b31 MS |
12 | The Zebra protocol (or ``ZAPI``) is used by protocol daemons to |
13 | communicate with the **zebra** daemon. | |
14 | ||
15 | Each protocol daemon may request and send information to and from the | |
16 | **zebra** daemon such as interface states, routing state, | |
17 | nexthop-validation, and so on. Protocol daemons may also install | |
18 | routes with **zebra**. The **zebra** daemon manages which routes are | |
19 | installed into the forwarding table with the kernel. Some daemons use | |
20 | more than one ZAPI connection. This is supported: each ZAPI session is | |
21 | identified by a tuple of: ``{protocol, instance, session_id}``. LDPD | |
22 | is an example: it uses a second, synchronous ZAPI session to manage | |
23 | label blocks. The default value for ``session_id`` is zero; daemons | |
24 | who use multiple ZAPI sessions must assign unique values to the | |
25 | sessions' ids. | |
ab2416a0 | 26 | |
610b34e1 QY |
27 | The Zebra protocol is a streaming protocol, with a common header. Version 0 |
28 | lacks a version field and is implicitly versioned. Version 1 and all subsequent | |
29 | versions have a version field. Version 0 can be distinguished from all other | |
30 | versions by examining the 3rd byte of the header, which contains a marker value | |
31 | of 255 (in Quagga) or 254 (in FRR) for all versions except version 0. The | |
32 | marker byte corresponds to the command field in version 0, and the marker value | |
33 | is a reserved command in version 0. | |
42fc5d26 | 34 | |
610b34e1 QY |
35 | Version History |
36 | --------------- | |
42fc5d26 | 37 | |
610b34e1 | 38 | - Version 0 |
42fc5d26 | 39 | |
610b34e1 QY |
40 | Used by all versions of GNU Zebra and all version of Quagga up to and |
41 | including Quagga 0.98. This version has no ``version`` field, and so is | |
42 | implicitly versioned as version 0. | |
42fc5d26 | 43 | |
610b34e1 | 44 | - Version 1 |
42fc5d26 | 45 | |
610b34e1 QY |
46 | Added ``marker`` and ``version`` fields, increased ``command`` field to 16 |
47 | bits. Used by Quagga versions 0.99.3 through 0.99.20. | |
42fc5d26 | 48 | |
610b34e1 QY |
49 | - Version 2 |
50 | ||
51 | Used by Quagga versions 0.99.21 through 0.99.23. | |
52 | ||
53 | - Version 3 | |
54 | ||
55 | Added ``vrf_id`` field. Used by Quagga versions 0.99.23 until FRR fork. | |
56 | ||
57 | - Version 4 | |
58 | ||
59 | Change marker value to 254 to prevent people mixing and matching Quagga and | |
60 | FRR daemon binaries. Used by FRR versions 2.0 through 3.0.3. | |
61 | ||
62 | - Version 5 | |
42fc5d26 | 63 | |
610b34e1 QY |
64 | Increased VRF identifier field from 16 to 32 bits. Used by FRR versions 4.0 |
65 | through 5.0.1. | |
42fc5d26 | 66 | |
610b34e1 QY |
67 | - Version 6 |
68 | ||
69 | Removed the following commands: | |
70 | ||
71 | * ZEBRA_IPV4_ROUTE_ADD | |
72 | * ZEBRA_IPV4_ROUTE_DELETE | |
73 | * ZEBRA_IPV6_ROUTE_ADD | |
74 | * ZEBRA_IPV6_ROUTE_DELETE | |
75 | ||
76 | Used since FRR version 6.0. | |
77 | ||
78 | ||
79 | Zebra Protocol Definition | |
80 | ========================= | |
42fc5d26 QY |
81 | |
82 | Zebra Protocol Header Field Definitions | |
83 | --------------------------------------- | |
84 | ||
c1a54c05 | 85 | Length |
610b34e1 | 86 | Total packet length including this header. |
ab2416a0 | 87 | |
c1a54c05 | 88 | Marker |
610b34e1 QY |
89 | Static marker. The marker value, when it exists, is 255 in all versions of |
90 | Quagga. It is 254 in all versions of FRR. This is to allow version 0 headers | |
91 | (which do not include version explicitly) to be distinguished from versioned | |
92 | headers. | |
ab2416a0 | 93 | |
c1a54c05 | 94 | Version |
610b34e1 QY |
95 | Zebra protocol version number. Clients should not continue processing |
96 | messages past the version field for versions they do not recognise. | |
c1a54c05 QY |
97 | |
98 | Command | |
610b34e1 QY |
99 | The Zebra protocol command. |
100 | ||
101 | ||
102 | Current Version | |
103 | ^^^^^^^^^^^^^^^ | |
104 | ||
105 | :: | |
106 | ||
107 | Version 5, 6 | |
108 | ||
109 | 0 1 2 3 | |
110 | 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | |
111 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
112 | | Length | Marker | Version | | |
113 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
114 | | VRF ID | | |
115 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
116 | | Command | | |
117 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
118 | ||
119 | ||
120 | Past Versions | |
121 | ^^^^^^^^^^^^^ | |
122 | ||
123 | :: | |
124 | ||
125 | Version 0 | |
126 | ||
127 | 0 1 2 3 | |
128 | 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | |
129 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
130 | | Length | Command | | |
131 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
132 | ||
133 | :: | |
134 | ||
135 | Version 1, 2 | |
136 | ||
137 | 0 1 2 3 | |
138 | 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | |
139 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
140 | | Length | Marker | Version | | |
141 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
142 | | Command | | |
143 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
144 | ||
145 | ||
146 | :: | |
147 | ||
148 | Version 3, 4 | |
149 | ||
150 | 0 1 2 3 | |
151 | 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | |
152 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
153 | | Length | Marker | Version | | |
154 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
155 | | VRF ID | Command | | |
156 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
ab2416a0 | 157 | |
ab2416a0 | 158 | |
42fc5d26 QY |
159 | Zebra Protocol Commands |
160 | ----------------------- | |
161 | ||
610b34e1 QY |
162 | +------------------------------------+-------+ |
163 | | Command | Value | | |
164 | +====================================+=======+ | |
165 | | ZEBRA_INTERFACE_ADD | 0 | | |
166 | +------------------------------------+-------+ | |
167 | | ZEBRA_INTERFACE_DELETE | 1 | | |
168 | +------------------------------------+-------+ | |
169 | | ZEBRA_INTERFACE_ADDRESS_ADD | 2 | | |
170 | +------------------------------------+-------+ | |
171 | | ZEBRA_INTERFACE_ADDRESS_DELETE | 3 | | |
172 | +------------------------------------+-------+ | |
173 | | ZEBRA_INTERFACE_UP | 4 | | |
174 | +------------------------------------+-------+ | |
175 | | ZEBRA_INTERFACE_DOWN | 5 | | |
176 | +------------------------------------+-------+ | |
177 | | ZEBRA_INTERFACE_SET_MASTER | 6 | | |
178 | +------------------------------------+-------+ | |
b9e6727a | 179 | | ZEBRA_INTERFACE_SET_PROTODOWN | 7 | |
610b34e1 | 180 | +------------------------------------+-------+ |
b9e6727a | 181 | | ZEBRA_ROUTE_ADD | 8 | |
610b34e1 | 182 | +------------------------------------+-------+ |
b9e6727a | 183 | | ZEBRA_ROUTE_DELETE | 9 | |
610b34e1 | 184 | +------------------------------------+-------+ |
b9e6727a | 185 | | ZEBRA_ROUTE_NOTIFY_OWNER | 10 | |
610b34e1 | 186 | +------------------------------------+-------+ |
b9e6727a | 187 | | ZEBRA_REDISTRIBUTE_ADD | 11 | |
610b34e1 | 188 | +------------------------------------+-------+ |
b9e6727a | 189 | | ZEBRA_REDISTRIBUTE_DELETE | 12 | |
610b34e1 | 190 | +------------------------------------+-------+ |
b9e6727a | 191 | | ZEBRA_REDISTRIBUTE_DEFAULT_ADD | 13 | |
610b34e1 | 192 | +------------------------------------+-------+ |
b9e6727a | 193 | | ZEBRA_REDISTRIBUTE_DEFAULT_DELETE | 14 | |
610b34e1 | 194 | +------------------------------------+-------+ |
b9e6727a | 195 | | ZEBRA_ROUTER_ID_ADD | 15 | |
610b34e1 | 196 | +------------------------------------+-------+ |
b9e6727a | 197 | | ZEBRA_ROUTER_ID_DELETE | 16 | |
610b34e1 | 198 | +------------------------------------+-------+ |
b9e6727a | 199 | | ZEBRA_ROUTER_ID_UPDATE | 17 | |
610b34e1 | 200 | +------------------------------------+-------+ |
b9e6727a | 201 | | ZEBRA_HELLO | 18 | |
610b34e1 | 202 | +------------------------------------+-------+ |
b9e6727a | 203 | | ZEBRA_CAPABILITIES | 19 | |
610b34e1 | 204 | +------------------------------------+-------+ |
b9e6727a | 205 | | ZEBRA_NEXTHOP_REGISTER | 20 | |
610b34e1 | 206 | +------------------------------------+-------+ |
b9e6727a | 207 | | ZEBRA_NEXTHOP_UNREGISTER | 21 | |
610b34e1 | 208 | +------------------------------------+-------+ |
b9e6727a | 209 | | ZEBRA_NEXTHOP_UPDATE | 22 | |
610b34e1 | 210 | +------------------------------------+-------+ |
b9e6727a | 211 | | ZEBRA_INTERFACE_NBR_ADDRESS_ADD | 23 | |
610b34e1 | 212 | +------------------------------------+-------+ |
b9e6727a | 213 | | ZEBRA_INTERFACE_NBR_ADDRESS_DELETE | 24 | |
610b34e1 | 214 | +------------------------------------+-------+ |
b9e6727a | 215 | | ZEBRA_INTERFACE_BFD_DEST_UPDATE | 25 | |
610b34e1 | 216 | +------------------------------------+-------+ |
b9e6727a | 217 | | ZEBRA_IMPORT_ROUTE_REGISTER | 26 | |
610b34e1 | 218 | +------------------------------------+-------+ |
b9e6727a | 219 | | ZEBRA_IMPORT_ROUTE_UNREGISTER | 27 | |
610b34e1 | 220 | +------------------------------------+-------+ |
b9e6727a | 221 | | ZEBRA_BFD_DEST_REGISTER | 29 | |
610b34e1 | 222 | +------------------------------------+-------+ |
b9e6727a | 223 | | ZEBRA_BFD_DEST_DEREGISTER | 30 | |
610b34e1 | 224 | +------------------------------------+-------+ |
b9e6727a | 225 | | ZEBRA_BFD_DEST_UPDATE | 31 | |
610b34e1 | 226 | +------------------------------------+-------+ |
b9e6727a | 227 | | ZEBRA_BFD_DEST_REPLAY | 32 | |
610b34e1 | 228 | +------------------------------------+-------+ |
b9e6727a | 229 | | ZEBRA_REDISTRIBUTE_ROUTE_ADD | 33 | |
610b34e1 | 230 | +------------------------------------+-------+ |
b9e6727a | 231 | | ZEBRA_REDISTRIBUTE_ROUTE_DEL | 34 | |
610b34e1 | 232 | +------------------------------------+-------+ |
b9e6727a | 233 | | ZEBRA_VRF_UNREGISTER | 35 | |
610b34e1 | 234 | +------------------------------------+-------+ |
b9e6727a | 235 | | ZEBRA_VRF_ADD | 36 | |
610b34e1 | 236 | +------------------------------------+-------+ |
b9e6727a | 237 | | ZEBRA_VRF_DELETE | 37 | |
610b34e1 | 238 | +------------------------------------+-------+ |
b9e6727a | 239 | | ZEBRA_VRF_LABEL | 38 | |
610b34e1 | 240 | +------------------------------------+-------+ |
b9e6727a | 241 | | ZEBRA_INTERFACE_VRF_UPDATE | 39 | |
610b34e1 | 242 | +------------------------------------+-------+ |
b9e6727a | 243 | | ZEBRA_BFD_CLIENT_REGISTER | 40 | |
610b34e1 | 244 | +------------------------------------+-------+ |
b9e6727a | 245 | | ZEBRA_BFD_CLIENT_DEREGISTER | 41 | |
610b34e1 | 246 | +------------------------------------+-------+ |
b9e6727a | 247 | | ZEBRA_INTERFACE_ENABLE_RADV | 42 | |
610b34e1 | 248 | +------------------------------------+-------+ |
b9e6727a | 249 | | ZEBRA_INTERFACE_DISABLE_RADV | 43 | |
610b34e1 | 250 | +------------------------------------+-------+ |
34ee41c6 | 251 | | ZEBRA_NEXTHOP_LOOKUP_MRIB | 44 | |
610b34e1 | 252 | +------------------------------------+-------+ |
b9e6727a | 253 | | ZEBRA_INTERFACE_LINK_PARAMS | 45 | |
610b34e1 | 254 | +------------------------------------+-------+ |
b9e6727a | 255 | | ZEBRA_MPLS_LABELS_ADD | 46 | |
610b34e1 | 256 | +------------------------------------+-------+ |
b9e6727a | 257 | | ZEBRA_MPLS_LABELS_DELETE | 47 | |
610b34e1 | 258 | +------------------------------------+-------+ |
b9e6727a | 259 | | ZEBRA_MPLS_LABELS_REPLACE | 48 | |
610b34e1 | 260 | +------------------------------------+-------+ |
b9e6727a | 261 | | ZEBRA_IPMR_ROUTE_STATS | 49 | |
610b34e1 | 262 | +------------------------------------+-------+ |
b9e6727a | 263 | | ZEBRA_LABEL_MANAGER_CONNECT | 50 | |
610b34e1 | 264 | +------------------------------------+-------+ |
b9e6727a | 265 | | ZEBRA_LABEL_MANAGER_CONNECT_ASYNC | 51 | |
610b34e1 | 266 | +------------------------------------+-------+ |
b9e6727a | 267 | | ZEBRA_GET_LABEL_CHUNK | 52 | |
610b34e1 | 268 | +------------------------------------+-------+ |
b9e6727a | 269 | | ZEBRA_RELEASE_LABEL_CHUNK | 53 | |
610b34e1 | 270 | +------------------------------------+-------+ |
b9e6727a | 271 | | ZEBRA_FEC_REGISTER | 54 | |
610b34e1 | 272 | +------------------------------------+-------+ |
b9e6727a | 273 | | ZEBRA_FEC_UNREGISTER | 55 | |
610b34e1 | 274 | +------------------------------------+-------+ |
b9e6727a | 275 | | ZEBRA_FEC_UPDATE | 56 | |
610b34e1 | 276 | +------------------------------------+-------+ |
b9e6727a | 277 | | ZEBRA_ADVERTISE_DEFAULT_GW | 57 | |
610b34e1 | 278 | +------------------------------------+-------+ |
b9e6727a | 279 | | ZEBRA_ADVERTISE_SVI_MACIP | 58 | |
610b34e1 | 280 | +------------------------------------+-------+ |
b9e6727a | 281 | | ZEBRA_ADVERTISE_SUBNET | 59 | |
610b34e1 | 282 | +------------------------------------+-------+ |
b9e6727a | 283 | | ZEBRA_ADVERTISE_ALL_VNI | 60 | |
610b34e1 | 284 | +------------------------------------+-------+ |
b9e6727a | 285 | | ZEBRA_LOCAL_ES_ADD | 61 | |
610b34e1 | 286 | +------------------------------------+-------+ |
b9e6727a | 287 | | ZEBRA_LOCAL_ES_DEL | 62 | |
610b34e1 | 288 | +------------------------------------+-------+ |
b9e6727a | 289 | | ZEBRA_VNI_ADD | 63 | |
610b34e1 | 290 | +------------------------------------+-------+ |
b9e6727a | 291 | | ZEBRA_VNI_DEL | 64 | |
610b34e1 | 292 | +------------------------------------+-------+ |
b9e6727a | 293 | | ZEBRA_L3VNI_ADD | 65 | |
610b34e1 | 294 | +------------------------------------+-------+ |
b9e6727a | 295 | | ZEBRA_L3VNI_DEL | 66 | |
610b34e1 | 296 | +------------------------------------+-------+ |
b9e6727a | 297 | | ZEBRA_REMOTE_VTEP_ADD | 67 | |
610b34e1 | 298 | +------------------------------------+-------+ |
b9e6727a | 299 | | ZEBRA_REMOTE_VTEP_DEL | 68 | |
610b34e1 | 300 | +------------------------------------+-------+ |
b9e6727a | 301 | | ZEBRA_MACIP_ADD | 69 | |
610b34e1 | 302 | +------------------------------------+-------+ |
b9e6727a | 303 | | ZEBRA_MACIP_DEL | 70 | |
610b34e1 | 304 | +------------------------------------+-------+ |
b9e6727a | 305 | | ZEBRA_IP_PREFIX_ROUTE_ADD | 71 | |
610b34e1 | 306 | +------------------------------------+-------+ |
b9e6727a | 307 | | ZEBRA_IP_PREFIX_ROUTE_DEL | 72 | |
610b34e1 | 308 | +------------------------------------+-------+ |
b9e6727a | 309 | | ZEBRA_REMOTE_MACIP_ADD | 73 | |
610b34e1 | 310 | +------------------------------------+-------+ |
b9e6727a | 311 | | ZEBRA_REMOTE_MACIP_DEL | 74 | |
610b34e1 | 312 | +------------------------------------+-------+ |
b9e6727a | 313 | | ZEBRA_DUPLICATE_ADDR_DETECTION | 75 | |
610b34e1 | 314 | +------------------------------------+-------+ |
b9e6727a | 315 | | ZEBRA_PW_ADD | 76 | |
610b34e1 | 316 | +------------------------------------+-------+ |
b9e6727a | 317 | | ZEBRA_PW_DELETE | 77 | |
610b34e1 | 318 | +------------------------------------+-------+ |
b9e6727a | 319 | | ZEBRA_PW_SET | 78 | |
610b34e1 | 320 | +------------------------------------+-------+ |
b9e6727a | 321 | | ZEBRA_PW_UNSET | 79 | |
610b34e1 | 322 | +------------------------------------+-------+ |
b9e6727a | 323 | | ZEBRA_PW_STATUS_UPDATE | 80 | |
610b34e1 | 324 | +------------------------------------+-------+ |
b9e6727a | 325 | | ZEBRA_RULE_ADD | 81 | |
610b34e1 | 326 | +------------------------------------+-------+ |
b9e6727a | 327 | | ZEBRA_RULE_DELETE | 82 | |
610b34e1 | 328 | +------------------------------------+-------+ |
b9e6727a | 329 | | ZEBRA_RULE_NOTIFY_OWNER | 83 | |
610b34e1 | 330 | +------------------------------------+-------+ |
b9e6727a | 331 | | ZEBRA_TABLE_MANAGER_CONNECT | 84 | |
610b34e1 | 332 | +------------------------------------+-------+ |
b9e6727a | 333 | | ZEBRA_GET_TABLE_CHUNK | 85 | |
610b34e1 | 334 | +------------------------------------+-------+ |
b9e6727a | 335 | | ZEBRA_RELEASE_TABLE_CHUNK | 86 | |
610b34e1 | 336 | +------------------------------------+-------+ |
b9e6727a | 337 | | ZEBRA_IPSET_CREATE | 87 | |
610b34e1 | 338 | +------------------------------------+-------+ |
b9e6727a | 339 | | ZEBRA_IPSET_DESTROY | 88 | |
610b34e1 | 340 | +------------------------------------+-------+ |
b9e6727a | 341 | | ZEBRA_IPSET_ENTRY_ADD | 89 | |
610b34e1 | 342 | +------------------------------------+-------+ |
b9e6727a | 343 | | ZEBRA_IPSET_ENTRY_DELETE | 90 | |
610b34e1 | 344 | +------------------------------------+-------+ |
b9e6727a | 345 | | ZEBRA_IPSET_NOTIFY_OWNER | 91 | |
610b34e1 | 346 | +------------------------------------+-------+ |
b9e6727a S |
347 | | ZEBRA_IPSET_ENTRY_NOTIFY_OWNER | 92 | |
348 | +------------------------------------+-------+ | |
349 | | ZEBRA_IPTABLE_ADD | 93 | | |
350 | +------------------------------------+-------+ | |
351 | | ZEBRA_IPTABLE_DELETE | 94 | | |
352 | +------------------------------------+-------+ | |
353 | | ZEBRA_IPTABLE_NOTIFY_OWNER | 95 | | |
354 | +------------------------------------+-------+ | |
355 | | ZEBRA_VXLAN_FLOOD_CONTROL | 96 | | |
356 | +------------------------------------+-------+ | |
357 | | ZEBRA_VXLAN_SG_ADD | 97 | | |
358 | +------------------------------------+-------+ | |
359 | | ZEBRA_VXLAN_SG_DEL | 98 | | |
360 | +------------------------------------+-------+ | |
361 | | ZEBRA_VXLAN_SG_REPLAY | 99 | | |
362 | +------------------------------------+-------+ | |
363 | | ZEBRA_MLAG_PROCESS_UP | 100 | | |
364 | +------------------------------------+-------+ | |
365 | | ZEBRA_MLAG_PROCESS_DOWN | 101 | | |
366 | +------------------------------------+-------+ | |
367 | | ZEBRA_MLAG_CLIENT_REGISTER | 102 | | |
368 | +------------------------------------+-------+ | |
369 | | ZEBRA_MLAG_CLIENT_UNREGISTER | 103 | | |
370 | +------------------------------------+-------+ | |
371 | | ZEBRA_MLAG_FORWARD_MSG | 104 | | |
372 | +------------------------------------+-------+ | |
cdfab162 MS |
373 | | ZEBRA_ERROR | 105 | |
374 | +------------------------------------+-------+ | |
375 | | ZEBRA_CLIENT_CAPABILITIES | 106 | | |
376 | +------------------------------------+-------+ | |
377 | | ZEBRA_OPAQUE_MESSAGE | 107 | | |
378 | +------------------------------------+-------+ | |
379 | | ZEBRA_OPAQUE_REGISTER | 108 | | |
380 | +------------------------------------+-------+ | |
381 | | ZEBRA_OPAQUE_UNREGISTER | 109 | | |
610b34e1 | 382 | +------------------------------------+-------+ |
d68e74b4 JU |
383 | | ZEBRA_NEIGH_DISCOVER | 110 | |
384 | +------------------------------------+-------+ | |
ac912324 JU |
385 | |
386 | Dataplane batching | |
d68e74b4 | 387 | ================== |
ac912324 JU |
388 | |
389 | Dataplane batching is an optimization feature that reduces the processing | |
390 | time involved in the user space to kernel space transition for every message we | |
391 | want to send. | |
392 | ||
393 | Design | |
394 | ----------- | |
395 | ||
396 | With our dataplane abstraction, we create a queue of dataplane context objects | |
397 | for the messages we want to send to the kernel. In a separate pthread, we | |
398 | loop over this queue and send the context objects to the appropriate | |
399 | dataplane. A batching enhancement tightly integrates with the dataplane | |
400 | context objects so they are able to be batch sent to dataplanes that support | |
401 | it. | |
402 | ||
403 | There is one main change in the dataplane code. It does not call | |
404 | kernel-dependent functions one-by-one, but instead it hands a list of work down | |
405 | to the kernel level for processing. | |
406 | ||
407 | Netlink | |
408 | ^^^^^^^ | |
409 | ||
410 | At the moment, this is the only dataplane that allows for batch sending | |
411 | messages to it. | |
412 | ||
413 | When messages must be sent to the kernel, they are consecutively added | |
414 | to the batch represented by the `struct nl_batch`. Context objects are firstly | |
415 | encoded to their binary representation. All the encoding functions use the same | |
416 | interface: take a context object, a buffer and a size of the buffer as an | |
417 | argument. It is important that they should handle a situation in which a message | |
418 | wouldn't fit in the buffer and return a proper error. To achieve a zero-copy | |
419 | (in the user space only) messages are encoded to the same buffer which will | |
420 | be passed to the kernel. Hence, we can theoretically hit the boundary of the | |
421 | buffer. | |
422 | ||
423 | Messages stored in the batch are sent if one of the conditions occurs: | |
424 | ||
425 | - When an encoding function returns the buffer overflow error. The context | |
426 | object that caused this error is re-added to the new, empty batch. | |
427 | ||
428 | - When the size of the batch hits certain limit. | |
429 | ||
430 | - When the namespace of a currently being processed context object is | |
431 | different from all the previous ones. They have to be sent through | |
432 | distinct sockets, so the messages cannot share the same buffer. | |
433 | ||
434 | - After the last message from the list is processed. | |
435 | ||
436 | As mentioned earlier, there is a special threshold which is smaller than | |
437 | the size of the underlying buffer. It prevents the overflow error and thus | |
438 | eliminates the case, in which a message is encoded twice. | |
439 | ||
440 | The buffer used in the batching is global, since allocating that big amount of | |
441 | memory every time wouldn't be most effective. However, its size can be changed | |
442 | dynamically, using hidden vtysh command: | |
443 | ``zebra kernel netlink batch-tx-buf (1-1048576) (1-1048576)``. This feature is | |
444 | only used in tests and shouldn't be utilized in any other place. | |
445 | ||
446 | For every failed message in the batch, the kernel responds with an error | |
447 | message. Error messages are kept in the same order as they were sent, so parsing the | |
448 | response is straightforward. We use the two pointer technique to match | |
449 | requests with responses and then set appropriate status of dataplane context | |
450 | objects. There is also a global receive buffer and it is assumed that whatever | |
451 | the kernel sends it will fit in this buffer. The payload of netlink error messages | |
452 | consists of a error code and the original netlink message of the request, so | |
453 | the batch response won't be bigger than the batch request increased by | |
454 | some space for the headers. |