forked from dmbaturin/iproute2-cheatsheet
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
1381 lines (1359 loc) · 76.1 KB
/
index.html
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
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>iproute2 cheat sheet</title>
<style type="text/css">
body {font: 13px/1 Helvetica,Arial,sans-serif; color: #444;}
h1, h2, h3, h4, h5, p { margin-bottom: 16px; padding: 0px;}
p { font-size: 14px; line-height: 20px; margin-top: 3px; max-width: 800px; }
a { color: #09F; margin: 0px; padding: 0px; vertical-align: baseline;}
li { line-height: 24px; margin-left: 44px;}
ul, ol { font-size: 14px; line-height: 20px;}
h3 { font-size: 21px;}
.wrapper { width: 1000px; margin: 0 auto; }
.preface { width: 100%; }
.section { border: #dadada solid 1px; width: 90%; margin-bottom: 2em; }
.subsection { padding-bottom: 2em; padding-left: 5px; padding-right: 5px; }
.subsection:nth-child(odd) { background-color: #ededed }
.code { font-family: monospace; } pre { margin-left: 50px; }
.copyright { text-align: center; width:90%;}
.contributors { border: #dadada solid 1px; width: 90%; }
hr { height: 1px; background-color: #aaaaaa; border: 0 none; }
</style>
<script type="text/javascript">
//<![CDATA[
function expand(id) { document.getElementById(id).display = "" }
// Generate table of contents
// Only two levels
// I could make it recursive, but we don't want infinite
// nesting in this document, right?
function gen_toc()
{
var toc_ol = document.getElementById('toc');
var sections = document.getElementsByClassName('section');
for(i=0; i<sections.length; i+=1)
{
var section_toc = document.createElement("li");
// Generate section link
// Name is taken from the first h3 occurence, if there's more
// than one h3, it's a mistake
var section_header = sections[i].getElementsByTagName('h3');
var section_name = section_header[0].innerHTML;
var section_link = document.createElement('a');
section_link.innerHTML = section_name;
section_link.href = "#" + section_name;
section_toc.appendChild(section_link);
// Create corresponding anchor and insert before the header
var section_anchor = document.createElement('a');
section_anchor.name = section_name;
sections[i].insertBefore(section_anchor, section_header[0]);
var subsections = sections[i].getElementsByClassName('subsection');
var subsection_toc = document.createElement('ol');
for(j=0;j<subsections.length;j+=1)
{
// Generate subsection link
// Name is taken from first h4 occurence
var subsection_item = document.createElement('li');
var subsection_link = document.createElement('a');
var subsection_header = subsections[j].getElementsByTagName('h4');
var subsection_name = subsection_header[0].innerHTML;
subsection_link.innerHTML = subsection_name;
subsection_link.href = "#" + subsection_name;
subsection_item.appendChild(subsection_link);
// Generate and insert subsection link
var subsection_anchor = document.createElement('a');
subsection_anchor.name= subsection_name;
subsections[j].insertBefore(subsection_anchor, subsection_header[0]);
subsection_toc.appendChild(subsection_item);
section_toc.appendChild(subsection_toc);
}
toc_ol.appendChild(section_toc);
}
}
//]]>
</script>
</head>
<body onload="gen_toc()">
<div class="wrapper">
<div class="preface">
<h3>Overview</h3>
<p>iproute2 is the Linux networking toolkit that replaced net-tools (ifconfig, route, arp etc.)</p>
<p>Old style network utilities like ifconfig and route are still there just for backwards compatibility
and do not provide access to new features like policy-based routing or network namespaces.</p>
<p>Note that iproute2 has been a <strong>standard Linux tool</strong> since the early 2000's. It's included in
every distro by default, or at least available from the repos (OpenWRT is one of the cases).</p>
<p>iproute2 was originally written by Alex Kuznetsov and is now maintained by Stephen Hemminger.</p>
<p>This document aims to provide comprehensive but easy to use documentation for the ip command
included in iproute2 package. There are more, such as ss (netstat replacement, fairly straightforward),
tc (QoS management), but documenting them in this style, especially tc, would be a separate big project.</p>
<p>Instead of listing commands and describing what they do, it lists common tasks network administrators
need to perform and gives commands to solve them, hence cheatsheet.</p>
<p>Contributions are always welcome, you can find the “source code” at
<a href="https://github.com/dmbaturin/iproute2-cheatsheet">github.com/dmbaturin/iproute2-cheatsheet</a>.</p>
<p>This document is provided “as is”, without any warranty. The authors are not liable for any
damage related to using it.</p>
<h3>General notes</h3>
<p>All commands that change any settings (that is, not just display them) require root privileges.</p>
<p>There are configuration files in /etc/iproute2, mainly for assinging symbolic names to network
stack entities such as routing tables. Those files are re-read every time you run the ip command and you don't need
to do anything to apply the changes.</p>
<h3>Typographic conventions</h3>
<p>Metasyntactic variables are written in shell-style syntax, ${something}. Optional command parts are in
square brackets.</p>
<ol id="toc">
</ol>
</div>
<div class="section">
<h3>Address management</h3>
<hr />
<p>In this section ${address} value should be a host address in dotted decimal format, and
${mask} can be either a dotted decimal subnet mask or a prefix length.
That is, both 192.0.2.10/24 and 192.0.2.10/255.255.255.0 are equally acceptable.</p>
<p> If you are not sure if something is a correct host address, use ipcalc or similar
program to check.</p>
<div class="subsection">
<h4>Show all addresses</h4>
<pre>ip address show</pre>
<span>All show commands can be used with -4 or -6 options to show only IPv4 or IPv6 addresses.</span>
</div>
<div class="subsection">
<h4>Show addresses for a single interface</h4>
<pre>ip address show ${interface name} </pre>
<span>Examples:</span>
<pre>ip address show eth0</pre>
</div>
<div class="subsection">
<h4>Show addresses only for running interfaces</h4>
<pre>ip address show up</pre>
</div>
<div class="subsection">
<h4>Show only static or dynamic IPv6 addresses</h4>
<span>Show only statically configured addresses:</span>
<pre>ip address show [dev ${interface}] permanent</pre>
<span>Show only addresses learnt via autoconfiguration:</span>
<pre>ip address show [dev ${interface}] dynamic</pre>
</div>
<div class="subsection">
<h4>Add an address to an interface</h4>
<pre>ip address add ${address}/${mask} dev ${interface name}</pre>
<span>Examples:</span>
<pre>ip address add 192.0.2.10/27 dev eth0</pre>
<pre>ip address add 2001:db8:1::/48 dev tun10</pre>
<p>You can add as many addresses as you want.</p>
<p>If you add more than one address, your machine will accept packets for
all of them. The first address you added will be used as source address for
outgoing traffic by default, it's often referred to as primary address.</p>
</div>
<div class="subsection">
<h4>Add an address with human-readable description</h4>
<pre>ip address add ${address}/${mask} dev ${interface name} label ${interface name}:${description} </pre>
<span>Examples:</span>
<pre>ip address add 192.0.2.1/24 dev eth0 label eth0:my_wan_address</pre>
<span>A label must start with the interface name followed by a colon due to some backwards compatibility issues,
otherwise you'll get an error.</span>
<h4>Notes</h4>
<p>For IPv6 addresses this command has no effect (address will be added, but without a label).</p>
</div>
<div class="subsection">
<h4>Delete an address</h4>
<pre>ip address delete ${address}/${prefix} dev ${interface name}</pre>
<span>Examples:</span>
<pre>ip address delete 192.0.2.1/24 dev eth0</pre>
<pre>ip address delete 2001:db8::1/64 dev tun1</pre>
<span>Interface name is required. Linux does allow the same address to be configured on multiple interfaces
and it has valid use cases.</span>
</div>
<div class="subsection">
<h4>Remove all addresses from an interface</h4>
<pre>ip address flush dev ${interface name}</pre>
<span>Examples:</span>
<pre>ip address flush dev eth1</pre>
</div>
<div class="subsection">
<p>By default this command removes both IPv4 and IPv6 addresses. If you want to remove only
IPv4 or IPv6 addresses, use “ip -4 address flush” or “ip -6 address flush”.</p>
<h4>Notes</h4> <br/>
<span>Note that there is no way to rearrange addresses and replace the primary address.
Make sure you set the primary address first.</span>
</div>
</div>
<div class="section">
<h3>Route management</h3>
<hr />
<p>For IPv4 routes, you can use either a prefix length or a dotted decimal subnet mask.
That is, both 192.0.2.0/24 and 192.0.2.0/255.255.255.0 are equally acceptable.</p>
<p><strong>Note:</strong> as per the section below, if you set up a static route,
and it becomes useless because the interface goes down, it will be removed and
<strong>never get back on its own</strong>. You may not have noticed this behaviour
because in many cases additional software (e.g. NetworkManager or rp-pppoe)
takes care of restoring routes associated with interfaces.</p>
<p>If you are going to use your Linux machine as a router, consider installing
a routing protocol suite such as <a href="http://quagga.net">Quagga</a>
or <a href="http://bird.network.cz">BIRD</a>. They keep track of interface status
and restore routes when a link goes up after going down. Of course they also allow you
to use dynamic routing protocols such as OSPF and BGP.</p>
<div class="subsection">
<h4>Connected routes</h4>
<p>Some routes appear in the system without explicit configuration (against your will).</p>
<p>Once you assign an address to an interface, the system calculates its network address
and creates a route to it (this is why the subnet mask is required). These routes are
called connected routes.</p>
<p>For example, if you assign 203.0.113.25/24 to eth0, a connected route to 203.0.113.0/24 network
will be created and the system will know that hosts from that network can be reached
directly.</p>
<p>When an interface goes down, connected routes associated with it are removed.
This is used for inaccessible gateway detection so routes through gateways that
went inaccessible are removed. Same mechanism prevents you from creating
routes through inaccessible gateways.</p>
</div>
<div class="subsection">
<h4>View all routes</h4>
<pre>ip route</pre>
<pre>ip route show</pre>
<span>You can use -4 and -6 options to view only IPv4 or IPv6 routes.
If no options given, IPv4 routes are displayed. To view IPv6 routes, use:</span>
<pre>ip -6 route</pre>
</div>
<div class="subsection">
<h4>View routes to a network and all its subnets</h4>
<pre>ip route show to root ${address}/${mask}</pre>
<span>For example, if you use 192.168.0.0/24 subnet in your network
and it's broken into 192.168.0.0/25 and 192.168.0.128/25, you can see
all those routes with:</span>
<pre>ip route show to root 192.168.0.0/24</pre>
<span>Note: the word "to" in this and other show commands is optional.</span>
</div>
<div class="subsection">
<h4>View routes to a network and all supernets</h4>
<pre>ip route show to match ${address}/${mask}</pre>
<span>If you want to view routes to 192.168.0.0/24 and all larger subnets,
use:</span>
<pre>ip route show to match 192.168.0.0/24</pre>
<span>As routers prefer more specific routes to less specific,
this is often useful for debugging in situations when traffic to specific
subnet is sent the wrong way because a route to it is missing
but routes to larger subnets exist.</span>
</div>
<div class="subsection">
<h4>View routes to exact subnet</h4>
<pre>ip route show to exact ${address}/${mask}</pre>
<span>If you want to see the routes to 192.168.0.0/24, but not to,
say 192.168.0.0/25 and 192.168.0.0/16, you can use:</span>
<pre>ip route show to exact 192.168.0.0/24</pre>
</div>
<div class="subsection">
<h4>View only the route actually used by the kernel</h4>
<pre>ip route get ${address}/${mask}</pre>
<span>Example:</span>
<pre>ip route get 192.168.0.0/24</pre>
<span>Note that in complex routing scenarios like multipath routing,
the result may be "correct but not complete", as it always shows
one route that will be used first. In most situations it's not
a problem, but never forget to look at the corresponding "show" command
output too.</span>
</div>
<div class="subsection">
<h4>View route cache (pre 3.6 kernels only)</h4>
<pre>ip route show cached</pre>
<span>Until the version 3.6, Linux used
route caching. In older kernels, this command displays the contents
of the route cache. It can be used with modifiers
described above. In newer kernels it does nothing.</span>
</div>
<div class="subsection">
<h4>Add a route via gateway</h4>
<pre>ip route add ${address}/${mask} via ${next hop}</pre>
<span>Examples:</span>
<pre>ip route add 192.0.2.128/25 via 192.0.2.1</pre>
<pre>ip route add 2001:db8:1::/48 via 2001:db8:1::1</pre>
</div>
<div class="subsection">
<h4>Add a route via interface</h4>
<pre>ip route add ${address}/${mask} dev ${interface name}</pre>
<span>Example:</span>
<pre>ip route add 192.0.2.0/25 dev ppp0</pre>
<span>Interface routes are commonly used with point-to-point interfaces
like PPP tunnels where next hop address is not required.</span>
</div>
<div class="subsection">
<h4>Change or replace a route</h4>
<p>You may use "change" command to change parameters of existing routes.
"Replace" command can be used to add new route or modify existing one if
it doesn't exist. Examples:</p>
<pre>ip route change 192.168.2.0/24 via 10.0.0.1</pre>
<pre>ip route replace 192.0.2.1/27 dev tun0</pre>
</div>
<div class="subsection">
<h4>Delete a route</h4>
<pre>ip route delete ${rest of the route statement}</pre>
<span>Examples:</span>
<pre>ip route delete 10.0.1.0/25 via 10.0.0.1</pre>
<pre>ip route delete default dev ppp0</pre>
</div>
<div class="subsection">
<h4>Default route</h4> <br/>
<span>There is a shortcut to add default route.</span>
<pre>ip route add default via ${address}/${mask}</pre>
<pre>ip route add default dev ${interface name}</pre>
<span>These are equivalent to:</span>
<pre>ip route add 0.0.0.0/0 ${address}/${mask}</pre>
<pre>ip route add 0.0.0.0/0 dev ${interface name}</pre>
<span>With IPv6 routes it also works and is equivalent to ::/0</span>
<pre>ip -6 route add default via 2001:db8::1</pre>
</div>
<div class="subsection">
<h4>Blackhole routes</h4>
<pre>ip route add blackhole ${address}/${mask}</pre>
<span>Examples:</span>
<pre>ip route add blackhole 192.0.2.1/32</pre>
<p>Traffic to destinations that match a blackhole route is silently discarded.</p>
<p>Blackhole routes have dual purpose. First one is straightforward, to discard traffic
sent to unwanted destinations, e.g. known malicious hosts.</p>
<p>The second one is less obvious and uses the "longest match rule" as per RFC1812.
In some cases you may want the router to think it has a route to a larger subnet,
while you are not using it as a whole,
e.g. when advertising the whole subnet via dynamic routing protocols. Large subnets
are commonly broken into smaller parts, so if your subnet is 192.0.2.0/24, and you
have assigned 192.0.2.1/25 and 192.0.2.129/25 to your interfaces, your system creates connected
routes to the /25's, but not the whole /24, and routing daemons may not want to
advertise /24 because you have no route to that exact subnet. The solution is to setup
a blackhole route to 192.0.2.0/24. Because routes to smaller subnets are preferred
over larger subnets, it will not affect actual routing, but will convince routing
daemons there's a route to the supernet.</p>
</div>
<div class="subsection">
<h4>Other special routes</h4>
<pre>ip route add unreachable ${address}/${mask}</pre>
<pre>ip route add prohibit ${address}/${mask}</pre>
<pre>ip route add throw ${address}/${mask}</pre>
<span>These routes make the system discard packets and reply with an ICMP error message to the sender.</span>
<dl>
<dt>unreachable</dt>
<dd>Sends ICMP "host unreachable".</dd>
<dt>prohibit</dt>
<dd>Sends ICMP "administratively prohibited".</dd>
<dt>throw</dt>
<dd>Sends "net unreachable".</dd>
</dl>
<p>Unlike blackhole routes, these can't be recommended for stopping unwanted traffic (e.g. DDoS)
because they generate a reply packet for every discarded packet and thus create even greater traffic flow.
They can be good for implementing internal access policies, but consider firewall for this purpose first.</p>
<p>"Throw" routes may be used for implementing policy-based routing, in non-default tables they
stop current table lookup, but don't send ICMP error messages.</p>
</div>
<div class="subsection">
<h4>Routes with different metric</h4>
<pre>ip route add ${address}/${mask} via ${gateway} metric ${number}</pre>
<span>Examples:</span>
<pre>ip route add 192.168.2.0/24 via 10.0.1.1 metric 5</pre>
<pre>ip route add 192.168.2.0 dev ppp0 metric 10</pre>
<p>If there are several routes to the same network with different metric value,
the one with <strong>the lowest</strong> metric will be preferred.</p>
<p>Important part of this concept is that when an interface goes down, routes
that would be rendered useless by this event disappear from the routing table (see the <a href="#Connected routes">Connected Routes</a> section), and
the system will fall back to higher metric routes.</p>
<p>This feature is commonly used to implement backup connections to important destinations.</p>
</div>
<div class="subsection">
<h4>Multipath routing</h4>
<pre>ip route add ${addresss}/${mask} nexthop via ${gateway 1} weight ${number} nexthop via ${gateway 2} weight ${number}</pre>
<p>Multipath routes make the system balance packets across several links according to the weight (higher weight is preferred, so
gateway/interface with weight of 2 will get roughly two times more traffic than another one with weight of 1). You can have as many gateways
as you want and mix gateway and interface routes, like:</p>
<pre>ip route add default nexthop via 192.168.1.1 weight 1 nexthop dev ppp0 weight 10</pre>
<p> <strong>Warning:</strong> the downside of this type of balancing is that packets are not guaranteed to be sent back
through the same link they came in. This is called "asymmetric routing". For routers that simply forward packets and don't
do any local traffic processing such as NAT, this is usually normal, and in some cases even unavoidable.</p>
<p>If your system does anything but forwarding packets between interfaces, this may cause problems with incoming connections
and some measures should be taken to prevent it.</p>
</div>
</div>
<div class="section">
<h3>Link management</h3>
<hr />
<p>Link is another name for network interface. Commands from "ip link" family perform operations
that are common for all interface types, like viewing link information or changing the MTU.</p>
<p>They also can create many types of interfaces, except for tunnel (IPIP, GRE etc.) and L2TPv3
pseudowires that have their own commands.</p>
<p>Note that interface name you set with "name ${name}" parameter of "ip link add" and "ip link set"
commands may be arbitrary, and may even contain unicode characters. However, it's better to stick with
ASCII because other programs may not handle unicode correctly.</p>
<p>Also note that other programs, such as iptables, may have their own link name format and length
restrictions, so it's better to use short alphanumeric names, and provide additional information in
<a href="#Set human-readable link description">link aliases</a>.</p>
<div class="subsection">
<h4>Show information about all links</h4>
<pre>ip link show</pre>
<pre>ip link list</pre>
<span>These commands are equivalent and can be used with the same arguments.</span>
</div>
<div class="subsection">
<h4>Show information about specific link</h4>
<pre>ip link show dev ${interface name}</pre>
<span>Examples:</span>
<pre>ip link show dev eth0</pre>
<pre>ip link show dev tun10</pre>
<span>The word "dev" may be omitted.</span>
</div>
<div class="subsection">
<h4>Bring a link up or down</h4>
<pre>ip link set dev ${interface name} up</pre>
<pre>ip link set dev ${interface name} down</pre>
<span>Examples:</span>
<pre>ip link set dev eth0 down</pre>
<pre>ip link set dev br0 up</pre>
<p><strong>Note:</strong> virtual links described below, like VLANs and bridges
are in <strong>down</strong> state immediately after creation. You need to bring them up to start using them.</p>
</div>
<div class="subsection">
<h4>Set human-readable link description</h4>
<pre>ip link set dev ${interface name} alias "${description}"</pre>
<span>Examples:</span>
<pre>ip link set dev eth0 alias "LAN interface"</pre>
<span>Link aliases show up in "ip link show" output, like:</span>
<pre>
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DEFAULT qlen 1000
link/ether 22:ce:e0:99:63:6f brd ff:ff:ff:ff:ff:ff
alias LAN interface
</pre>
</div>
<div class="subsection">
<h4>Rename an interface</h4>
<pre>ip link set dev ${old interface name} name ${new interface name}</pre>
<span>Examples:</span>
<pre>ip link set dev eth0 name lan</pre>
<p>Note that you can't rename an active interface. You need to bring it down
before doing it.</p>
</div>
<div class="subsection">
<h4>Change link layer address (usually MAC address)</h4>
<pre>ip link set dev ${interface name} address ${address}</pre>
<p>Link layer address is a pretty broad concept. The most known
example is MAC address for ethernet devices. To change MAC
address you would need something like:</p>
<pre>ip link set dev eth0 address 22:ce:e0:99:63:6f</pre>
</div>
<div class="subsection">
<h4>Change link MTU</h4>
<pre>ip link set dev ${interface name} mtu ${MTU value}</pre>
<span>Examples:</span>
<pre>ip link set dev tun0 mtu 1480</pre>
<p>MTU stands for "Maximum Transmission Unit", the maximum size
of a frame an interface can transmit at once.</p>
<p>Apart from reducing fragmentation in tunnels like
in example above, this is also used to increase performance of
gigabit ethernet links that support so called "jumbo frames"
(frames up to 9000 bytes large). If all your equipment
supports gigabit ethernet, you may want to do something like
<pre>ip link set dev eth0 mtu 9000</pre>
<p>Note that you may need to configure it on your L2 switches too,
some of them have it disables by default.</p>
</div>
<div class="subsection">
<h4>Delete a link</h4>
<pre>ip link delete dev ${interface name}</pre>
<p>Obviously, only virtual links like VLANs or bridges can be deleted.</p>
</div>
<div class="subsection">
<h4>Enable or disable multicast on an interface</h4>
<pre>ip link set ${interface name} multicast on</pre>
<pre>ip link set ${interface name} multicast off</pre>
<p>Unless you really understand what you are doing, better not to touch this.</p>
</div>
<div class="subsection">
<h4>Enable or disable ARP on an interface</h4>
<pre>ip link set ${interface name} arp on</pre>
<pre>ip link set ${interface name} arp off</pre>
<p>One may want to disable ARP to enforce a security policy and allow only specific MACs
to communicate with the interface. In this case neighbor table entries for whitelisted MACs
should be created manually (see <a href="#Neighbor (ARP and NDP) tables management">neighbor table management</a>
section), or nothing will be able to communicate with that interface. </p>
<p>In most cases it's better to configure MAC policy on an access layer switch though.
Do not change this flag unless you are sure what you are going to do and why.</p>
</div>
<div class="subsection">
<h4>Create a VLAN interface</h4>
<pre>ip link add name ${VLAN interface name} link ${parent interface name} type vlan id ${tag}</pre>
<span>Examples:</span>
<pre>ip link add name eth0.110 link eth0 type vlan id 110</pre>
<p>The only type of VLAN supported in Linux is IEEE 802.1q VLAN, legacy implementations like ISL
are not supported.</p>
<p>Once you create a VLAN interface, all frames tagged with ${tag} you specified in id option
received by ${parent interface} will be processed by that VLAN interface.</p>
<p>eth0.100 name format is traditional, but not required, you can name the interface as you want,
just like with other interface types.</p>
<p>VLANs can be created over bridge, bonding and other interfaces capable of processing ethernet frames too.</p>
</div>
<div class="subsection">
<h4>Create a QinQ interface (VLAN stacking)</h4>
<pre>ip link add name ${service interface} link ${physical interface} type vlan proto 802.1ad id ${service tag}</pre>
<pre>ip link add name ${client interface} link ${service interface} type vlan proto 802.1q id ${client tag}</pre>
<span>Example:</span>
<pre>ip link add name eth0.100 link eth0 type vlan proto 802.1ad id 100 # Create service tag interface</pre>
<pre>ip link add name eth0.100.200 link eth0.100 type vlan proto 802.1q id 200 # Create client tag interface</pre>
<p>VLAN stacking (aka 802.1ad QinQ) is a way to transmit VLAN tagged traffic over another VLAN. The common use case
for it is like this: suppose you are a service provider and you have a customer who wants to use your network
infrastructure to connect parts of their network to each other. They use multiple VLANs in their network, so
an ordinary rented VLAN is not an option. With QinQ you can add a second tag to the customer traffic when it enters your network
and remove that tag when it exits, so there are no conflicts and you don't need to waste VLAN numbers.</p>
<p>The service tag is the VLAN tag the provider uses to carry client traffic through their network. The client tag
is the tag set by the customer.</p>
<p>Note that link MTU for the client VLAN interface is not adjusted automatically, you need to take care
of it yourself and either decrease the client interface MTU by at least 4 bytes, or increase the parent MTU accordingly.</p>
<p>Standards-compliant QinQ is available since Linux 3.10.</p>
</div>
<div class="subsection">
<h4>Create pseudo-ethernet (aka macvlan) interface</h4>
<pre>ip link add name ${macvlan interface name} link ${parent interface} type macvlan</pre>
<span>Examples:</span>
<pre>ip link add name peth0 link eth0 type macvlan</pre>
<p>You can think of macvlan interfaces as additional virtual MAC addresses on the parent interface.
They look like normal ethernet interfaces from user point of view, and handle all traffic for
MAC address they are assigned with received by their parent interface.</p>
<p>This is commonly used for testing, or for using several instances of a service identified by
MAC when only one physical interface is available.</p>
<p>They also can be used just for IP address separation instead of assigning multiple addresses
to the same physical interface, especially if some service can't operate on a secondary address properly.</p>
</div>
<div class="subsection">
<h4>Create a dummy interface</h4>
<pre>ip link add name ${dummy interface name} type dummy</pre>
<span>Examples:</span>
<pre>ip link add name dummy0 type dummy</pre>
<p>Dummy interfaces work pretty much like loopback interfaces, just there can be as many
of them as you want.</p>
<p>The first purpose of them is for communication of programs inside the host.</p>
<p>The second purpose exploits the fact they are always up (unless administratively taken down).
This is often used to assign service addresses to them on routers with more than one physical
interface. As long as the traffic to the address assigned to a loopback or dummy interface
is routed to the machine that owns it, you can access it through any of its interfaces.</p>
</div>
<div class="subsection">
<h4>Create a bridge interface</h4>
<pre>ip link add name ${bridge name} type bridge</pre>
<span>Examples:</span>
<pre>ip link add name br0 type bridge</pre>
<p>Bridge interfaces are virtual ethernet switches. They can be used to relay traffic
transparently between ethernet interfaces, and, increasingly common, as ethernet switches
for virtual machines running inside hypervisors.</p>
<p>You can assign an IP address to a bridge and it will be visible from all bridge ports.</p>
<p>If this command fails, check if "bridge" module is loaded.</p>
</div>
<div class="subsection">
<h4>Add an interface to bridge</h4>
<pre>ip link set dev ${interface name} master ${bridge name}</pre>
<span>Examples:</span>
<pre>ip link set dev eth0 master br0</pre>
<p>Interface you added to a bridge becomes a virtual switch port. It operates only on datalink
layer and ceases all network layer operation.</p>
</div>
<div class="subsection">
<h4>Remove interface from bridge</h4>
<pre>ip link set dev ${interface name} nomaster</pre>
<span>Examples:</span>
<pre>ip link set dev eth0 nomaster</pre>
</div>
<div class="subsection">
<h4>Create a bonding interface</h4>
<pre>ip link add name ${name} type bond</pre>
<span>Examples:</span>
<pre>ip link add name bond1 type bond</pre>
<p><strong>Note:</strong> This is not enough to configure bonding (link aggregation)
in any meaningful way. You need to set up bonding parameters according to your situation.
This is far beyond the cheat sheet scope, so consult the documentation. </p>
<p>Interfaces are added to the bond group the same way to bridge group, just note that you can't
add it until you take it down.</p>
</div>
<div class="subsection">
<h4>Create an intermediate functional block interface</h4>
<pre>ip link add ${interface name} type ifb</pre>
<span>Example:</span>
<pre>ip link add ifb10 type ifb</pre>
<p>Intermediate functional block devices are used for traffic redirection and mirroring
in conjunction with tc. This is also far beyond the scope of this document, consult tc
documentation.</p>
</div>
<div class="subsection">
<h4>Create a pair of virtual ethernet devices</h4>
<p>Virtual ethernet (veth) devices always come in pairs and work as a bidirectional pipe,
whatever comes into one of them, comes out of another. They are used in conjunction with
system partitioning features such as network namespaces and containers (OpenVZ and LXC)
for connecting one partition to another.</p>
<pre>ip link add name ${first device name} type veth peer name ${second device name}</pre>
<span>Examples:</span>
<pre>ip link add name veth-host type veth peer name veth-guest</pre>
<p><strong>Note:</strong> virtual ethernet devices are created in UP state, no need to
bring them up manually after creation.</p>
</div>
</div>
<div class="section">
<h3>Link group management</h3>
<hr />
<p>Link groups are similar to port ranges found in managed switches. You can add network
interfaces to a numbered group and perform operations on all the interfaces from that group
at once.</p>
<p>Links not assigned to any group belong to group 0 aka "default".</p>
<div class="subsection">
<h4>Add an interface to a group</h4>
<pre>ip link set dev ${interface name} group ${group number}</pre>
<span>Examples:</span>
<pre>ip link set dev eth0 group 42</pre>
<pre>ip link set dev eth1 group 42</pre>
</div>
<div class="subsection">
<h4>Remove an interface from a group</h4>
<p>This can be done by assigning it to the default group.</p>
<pre>ip link set dev ${interface name} group 0</pre>
<pre>ip link set dev ${interface} group default</pre>
<span>Examples:</span>
<pre>ip link set dev tun10 group 0</pre>
</div>
<div class="subsection">
<h4>Assign a symbolic name to a group</h4>
<p>Group names are stored in /etc/iproute2/group file. Symbolic name "default"
for group 0 comes exactly from there. You can add your own, one per line,
following the same "${number} ${name}" format. You can have up to 255 named groups.</p>
<p>Once you configured a group name, number and name can be used interchangeably
in ip commands.</p>
<span>Example:</span>
<pre>echo "10 customer-vlans" >> /etc/iproute2/group</pre>
<span>After that you can use that name in all operations, like in</span>
<pre>ip link set dev eth0.100 group customer-vlans</pre>
</div>
<div class="subsection">
<h4>Perform an operation on a group</h4>
<pre>ip link set group ${group number} ${operation and arguments}</pre>
<span>Examples:</span>
<pre>ip link set group 42 down</pre>
<pre>ip link set group uplinks mtu 1200</pre>
</div>
<div class="subsection">
<h4>View information about links from specific group</h4>
<p>Use usual information viewing command with "group ${group}" modifier.</p>
<span>Examples:</span>
<pre>ip link list group 42</pre>
<pre>ip address show group customers</pre>
</div>
</div>
<div class="section">
<h3>Tun and Tap devices</h3>
<hr />
<p>Tun and tap devices allow userspace programs to emulate a network
device. When the userspace program opens them they get a file
descriptor. Packets routed by the kernel networking stack to the
device are read from the file descriptor, data the userspace
program writes to the file descriptor are injected as local
outgoing packets into the networking stack. The difference between
the two is:
</p>
<ul>
<li>tap sends and receives raw Ethernet frames.</li>
<li>tun sends and receives raw IP packets.</li>
</ul>
<p>The commands listed here manipulate persistent tun/tap devices.
There is another sort. Transient tun/tap devices are created by the
userspace program when they open a special device, and are destroyed
automatically when the associated file descriptor is closed.
</p>
<div class="subsection">
<h4>Add an tun/tap device useable by root</h4>
<pre>ip tuntap add dev ${interface name} mode ${mode}</pre>
<span>Examples:</span>
<pre>ip tuntap add dev tun0 mode tun</pre>
<pre>ip tuntap add dev tap9 mode tap</pre>
</div>
<div class="subsection">
<h4>Add an tun/tap device usable by an ordinary user</h4>
<pre>ip tuntap add dev ${interface name} mode ${mode} user ${user} group ${group}</pre>
<span>Example:</span>
<pre>ip tuntap add dev tun1 mode tun user me group mygroup</pre>
<pre>ip tuntap add dev tun2 mode tun user 1000 group 1001</pre>
</div>
<div class="subsection">
<h4>Add an tun/tap device using an alternate packet format</h4>
<p>Add meta information to each packet received over the file
descriptor. Very few programs expect this information, and
including it when it isn't expected will break things.
</p>
<pre>ip tuntap add dev ${interface name} mode ${mode} pi</pre>
<span>Example:</span>
<pre>ip tuntap add dev tun1 mode tun pi</pre>
</div>
<div class="subsection">
<h4>Add an tun/tap ignoring flow control</h4>
<p>Normally packets sent to a tun/tap device travel in the same way
as packets sent to any other device: they are put on a queue handled by the
traffic control engine (which is configured by the tc command).
This can be bypassed, thus disabling the traffic control engine
for this tun/tap device.
</p>
</p>
<pre>ip tuntap add dev ${interface name} mode ${mode} one_queue</pre>
<span>Example:</span>
<pre>ip tuntap add dev tun1 mode tun one_queue</pre>
</div>
<div class="subsection">
<h4>Delete tun/tap device</h4>
<pre>ip tuntap del dev ${interface name}</pre>
<span>Examples:</span>
<pre>ip tuntap del dev tun0 name}</pre>
</div>
</div>
<div class="section">
<h3>Neighbor (ARP and NDP) tables management</h3>
<p>For ladies and gentlemen who prefer UK spelling, this command family supports "neighbour" spelling too.</p>
<hr />
<div class="subsection">
<h4>View neighbor tables</h4>
<pre>ip neighbor show</pre>
<p>All "show" commands support -4 and -6 options to view only IPv4 (ARP) or IPv6 (NDP) neighbors. By default
all neighbors are displayed.</p>
</div>
<div class="subsection">
<h4>View neighbors for single interface</h4>
<pre>ip neighbor show dev ${interface name}</pre>
<span>Examples:</span>
<pre>ip neighbor show dev eth0</pre>
</div>
<div class="subsection">
<h4>Flush table for an interface</h4>
<pre>ip neighbor flush dev ${interface name}</pre>
<span>Examples:</span>
<pre>ip neighbor flush dev eth1</pre>
</div>
<div class="subsection">
<h4>Add a neighbor table entry</h4>
<pre>ip neighbor add ${network address} lladdr ${link layer address} dev ${interface name}</pre>
<span>Examples:</span>
<pre>ip neighbor add 192.0.2.1 lladdr 22:ce:e0:99:63:6f dev eth0</pre>
<p>One of the use cases for it is to add static entry for an interface with disabled ARP to
restrict interface usage only by hosts with specific MAC addresses.</p>
</div>
<div class="subsection">
<h4>Delete a neighbor table entry</h4>
<pre>ip neighbor delete ${network address} lladdr ${link layer address} dev ${interface name}</pre>
<span>Examples:</span>
<pre>ip neighbor delete 192.0.2.1 lladdr 22:ce:e0:99:63:6f dev eth0</pre>
<p>Allows to delete a static entry, or get rid ot an automatically learnt entry without flushing the table.</p>
</div>
</div>
<div class="section">
<h3>Tunnel management</h3>
<hr />
<p>Tunnels are "network wormholes" that look like normal interfaces,
but packets sent through them are encapsulated into another protocol
and sent to the other side of tunnel through multiple hosts, then
decapsulated and processed in usual way, so you can pretend two
machines have direct connectivity, while they in fact do not.</p>
<p>This is often used for virtual private networks (in conjunction with
encrypted transport protocols like IPsec), or connecting networks
that use some protocol via an intermediate network that does not use it
(e.g. IPv6 networks separated by an IPv4-only segment).</p>
<p><strong>Note:</strong> tunnels on their own offer zero security.
They are as secure as their underlying network. So if you need
security, use them over an encrypted transport, e.g. IPsec.</p>
<p>Linux currently supports IPIP (IPv4 in IPv4), SIT (IPv6 in IPv4),
IP6IP6 (IPv6 in IPv6), IPIP6 (IPv4 in IPv6), GRE (virtually anything
in anything), and, in very recent versions, VTI (IPv4 in IPsec).</p>
<p>Note that tunnels are created in DOWN state, you need to bring them up.</p>
<p>In this section ${local endpoint address} and ${remote endpoint address}
refer to addresses assigned to physical interfaces of endpoint. ${address}
refers to the address assigned to tunnel interface.</p>
<div class="subsection">
<h4>Create an IPIP tunnel</h4>
<pre>ip tunnel add ${interface name} mode ipip local ${local endpoint address} remote ${remote endpoint address}</pre>
<span>Examples:</span>
<pre>ip tunnel add tun0 mode ipip local 192.0.2.1 remote 198.51.100.3</pre>
<pre>ip link set dev tun0 up</pre>
<pre>ip address add 10.0.0.1/30 dev tun0</pre>
</div>
<div class="subsection">
<h4>Create a SIT tunnel</h4>
<pre>sudo ip tunnel add ${interface name} mode sit local ${local endpoint address} remote ${remote endpoint address}</pre>
<span>Examples:</span>
<pre>ip tunnel add tun9 mode sit local 192.0.2.1 remote 198.51.100.3</pre>
<pre>ip link set dev tun9 up</pre>
<pre>ip address add 2001:db8:1::1/64 dev tun9</pre>
<p>This type of tunnels is commonly used to provide an IPv4-connected network with
IPv6 connectivity. There are so called "tunnel brokers" that provide it to everyone interested,
e.g. Hurricane Electric <a href="http://tunnelbroker.net">tunnelbroker.net</a>.</p>
</div>
<div class="subsection">
<h4>Create an IPIP6 tunnel</h4>
<pre> ip -6 tunnel add ${interface name} mode ipip6 local ${local endpoint address} remote ${remote endpoint address}</pre>
<span>Examples:</span>
<pre>ip -6 tunnel add tun8 mode ipip6 local 2001:db8:1::1 remote 2001:db8:1::2</pre>
<p>This type of tunnels will be widely used when transit operators phase IPv4 out (i.e. not any soon).</p>
</div>
<div class="subsection">
<h4>Create an IP6IP6 tunnel</h4>
<pre>ip -6 tunnel add ${interface name} mode ip6ip6 local ${local endpoint address} remote ${remote endpoint address}</pre>
<span>Examples:</span>
<pre>ip -6 tunnel add tun3 mode ip6ip6 local 2001:db8:1::1 remote 2001:db8:1::2</pre>
<pre>ip link set dev tun3 up</pre>
<pre>ip address add 2001:db8:2:2::1/64 dev tun3</pre>
<p>Just like IPIP6 these ones aren't going to be generally useful any soon.</p>
</div>
<div class="subsection">
<h4>Create a gretap (ethernet over GRE) device</h4>
<pre>ip link add ${interface name} type gretap local ${local endpoint address} remote ${remote endpoint address}</pre>
<span>Examples:</span>
<pre>ip link add gretap0 type gretap local 192.0.2.1 remote 203.0.113.3</pre>
<p>This type of tunnels encapsulates ethernet frames into IPv4 packets.</p>
<p>Recent kernel and iproute2 versions also support gretap over IPv6, you need to replace the mode with "ip6gretap"
to create an IPv6-based link.</p>
<p>This probably should have been in "Links management" section, but as it involves encapsulation, it's here.
Tunnel interface created this way looks like an L2 link, and it can be added to a bridge group. This is used
to connect L2 segments via a routed network.</p>
</div>
<div class="subsection">
<h4>Create a GRE tunnel</h4>
<pre>ip tunnel add ${interface name} mode gre local ${local endpoint address} remote ${remote endpoint address}</pre>
<span>Examples:</span>
<pre>ip tunnel add tun6 mode gre local 192.0.2.1 remote 203.0.113.3</pre>
<pre>ip link set dev tun6 up</pre>
<pre>ip address add 192.168.0.1/30 dev tun6</pre>
<pre>ip address add 2001:db8:1::1/64 dev tun6</pre>
<p>GRE can encapsulate both IPv4 and IPv6 at the same time. However, by default it uses IPv4 for transport,
for GRE over IPv6 there is a separate tunnel mode, "ip6gre".</p>
</div>
<div class="subsection">
<h4>Create multiple GRE tunnels to the same endpoint</h4>
<pre>ip tunnel add ${interface name} mode gre local ${local endpoint address} remote ${remote endpoint address} key ${key value}</pre>
<span>Examples:</span>
<pre>ip tunnel add tun4 mode gre local 192.0.2.1 remote 203.0.113.6 key 123</pre>
<pre>ip tunnel add tun5 mode gre local 192.0.2.1 remote 203.0.113.6 key 124</pre>
<p>Keyed tunnels can be used at the same time to unkeyed too. Key may be in dotted decimal IPv4-like format.</p>
<p>Note that key does not add any security to the tunnel. It's just an identifier used to distinguish one tunnel from another.</p>
</div>
<div class="subsection">
<h4>Create a point-to-multipoint GRE tunnel</h4>
<pre>ip tunnel add ${interface name} mode gre local ${local endpoint address} key ${key value}</pre>
<span>Examples:</span>
<pre>ip tunnel add tun8 mode gre local 192.0.2.1 key 1234</pre>
<pre>ip link set dev tun8 up</pre>
<pre>ip address add 10.0.0.1/27 dev tun8</pre>
<p>Note the absence of ${remote endpoint address}. This is the same to what is called "mode gre multipoint" in Cisco IOS.</p>
<p>In the absence of remote endpoint address the key is the only way to identify the tunnel traffic, so ${key value} is required.</p>
<p>This type of tunnels allows you to communicate with multiple endpoints by using the same tunnel interface. It's commonly used in
complex VPN setups with multiple endpoints communicating to one another (in Cisco terminology, "dynamic multipoint VPN").</p>
<p>As there is no explicit remote endpoint address, obviously it is not enough to just create a tunnel. Your system needs to know
where the other endpoints are.</p>
<p>In real life NHRP (Next Hop Resolution Protocol) is used for it. For testing you can add peers manually (given remote endpoint
uses 203.0.113.6 address on its physical interface and 10.0.0.2 on the tunnel):</p>
<pre>ip neighbor add 10.0.0.2 lladdr 203.0.113.6 dev tun8</pre>
<p>You will have to do it on the remote endpoint too, like:</p>
<pre>ip neighbor add 10.0.0.1 lladdr 192.0.2.1 dev tun8</pre>
<p>Note that link-layer address and neighbor address are both IP addresses, so they are on the same OSI layer.
This one of the cases where link-layer address concept gets interesting.</p>
</div>
<div class="subsection">
<h4>Create a GRE tunnel over IPv6</h4>
<p>Recent kernel and iproute2 versions support GRE over IPv6. Point-to-point with no key:</p>
<pre>ip -6 tunnel add name ${interface name} mode ip6gre local ${local endpoint} remote ${remote endpoint}</pre>
<p>It should support all options and features supported by the IPv4 GRE described above.</p>
</div>
<div class="subsection">
<h4>Delete a tunnel</h4>
<pre>ip tunnel del ${interface name}</pre>
<span>Examples:</span>
<pre>ip tunnel del gre1</pre>
<p>Note that in older iproute2 versions this command did not support the full "delete" word, only "del".
Recent versions allow both full and abbreviated forms (tested in iproute2-ss131122).</p>
</div>
<div class="subsection">
<h4>Modify a tunnel</h4>
<pre>ip tunnel change ${interface name} ${options}</pre>
<span>Examples:</span>
<pre>ip tunnel change tun0 remote 203.0.113.89</pre>
<pre>ip tunnel change tun10 key 23456</pre>
<p> <strong>Note:</strong> Apparently you can't add a key to previously unkeyed tunnel.
Not sure if it's a bug or a feature. Also, you can't change tunnel mode on the fly,
for obvious reasons.</p>
</div>
<div class="subsection">
<h4>View tunnel information</h4>
<pre>ip tunnel show</pre>
<pre>ip tunnel show ${interface name}</pre>
<span>Examples:</span>
<pre>$ip tun show tun99
tun99: gre/ip remote 10.46.1.20 local 10.91.19.110 ttl inherit
</pre>
</div>
</div>
<div class="section">
<h3>L2TPv3 pseudowire management</h3>
<hr />
<p><a href="http://tools.ietf.org/html/rfc3931">L2TPv3</a> is a tunneling
protocol commonly used for L2 pseudowires.</p>
<p>In many distros L2TPv3 is compiled as a module, and may not be loaded by default.
If you get a "RTNETLINK answers: No such file or directory" and "Error talking to the kernel" message
to any "ip l2tp" command, this is likely the case. Load <strong>l2tp_netlink</strong> and
<strong>l2tp_eth</strong> modules. If you want to use L2TPv3 over IP rather than UDP, also load
<strong>l2tp_ip</strong>.</p>
<p>Compared to other tunneling protocol implementations in Linux, L2TPv3 terminology is somewhat
reversed. You create a <em>tunnel</em>, and then bind <em>sessions</em> to it. You can bind
multiple sessions with different identifiers to the same tunnel. Virtual network interfaces
(by default named l2tpethX) are associated with <em>sessions</em>.</p>
<p> <strong>Note:</strong> Linux kernel implements only handling of data frames, so you can create
only unmanaged tunnels with iproute2, with all settings configured manually on both sides.
If you want to use L2TP for remote access VPN or something else other than fixed
pseudowire, you need a userspace daemon to handle it. This is outside of this document scope.</p>
<div class="subsection">
<h4>Create an L2TPv3 tunnel over UDP</h4>
<pre>
ip l2tp add tunnel \
tunnel_id ${local tunnel numeric identifier} \
peer_tunnel_id ${remote tunnel numeric identifier} \
udp_sport ${source port} \
udp_dport ${destination port} \
encap udp \
local ${local endpoint address} \
remote ${remote endpoint address}
</pre>
<span>Examples:</span>
<pre>
ip l2tp add tunnel \
tunnel_id 1 \
peer_tunnel_id 1 \
udp_sport 5000 \
udp_dport 5000 \
encap udp \
local 192.0.2.1 \
remote 203.0.113.2
</pre>
<p><strong>Note:</strong> Tunnel identifiers and other settings on both endpoints must match.</p>
</div>
<div class="subsection">
<h4>Create an L2TPv3 tunnel over IP</h4>
<pre>ip l2tp add tunnel \
tunnel_id ${local tunnel numeric identifier} \
peer_tunnel_id {remote tunnel numeric identifier } \
encap ip \
local 192.0.2.1 \
remote 203.0.113.2
</pre>
<p>L2TPv3 encapsulated directly into IP offers less overhead,
bug generally is unable to pass through NAT.</p>
</div>
<div class="subsection">
<h4>Create an L2TPv3 session</h4>
<pre>ip l2tp add session tunnel_id ${local tunnel identifier} \
session_id ${local session numeric identifier} \
peer_session_id ${remote session numeric identifier}
</pre>
<span>Examples:</span>
<pre>ip l2tp add session tunnel_id 1 \
session_id 10 \
peer_session_id 10
</pre>
<p> <strong>Notes:</strong> tunnel_id value must match a value of previously created tunnel.
Session identifiers on both endpoints must match.</p>
<p>Once you create a tunnel and a session, l2tpethX interface will appear, in down state. Change the state
to up and bridge it with another interface or assign an address.</p>
</div>
<div class="subsection">
<h4>Delete an L2TPv3 session</h4>
<pre>ip l2tp del session tunnel_id ${tunnel identifier} \
session_id ${session identifier}
</pre>
<span>Examples</span>
<pre>ip l2tp del session tunnel_id 1 session_id 1</pre>
</div>
<div class="subsection">
<h4>Delete an L2TPv3 tunnel</h4>
<pre>ip l2tp del tunnel tunnel_id ${tunnel identifier}</pre>
<span>Examples</span>
<pre>ip l2tp del tunnel tunnel_id 1</pre>
<p> <strong>Note:</strong> You need to delete all sessions associated
with a tunnel before deleting it.</p>
</div>
<div class="subsection">
<h4>View L2TPv3 tunnel information</h4>
<pre>ip l2tp show tunnel</pre>
<pre>ip l2tp show tunnel tunnel_id ${tunnel identifier}</pre>
<span>Examples:</span>
<pre>ip l2tp show tunnel tunnel_id 12</pre>
</div>
<div class="subsection">