logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

ip-l2tp.8 (13294B)


  1. .TH IP\-L2TP 8 "19 Apr 2012" "iproute2" "Linux"
  2. .SH "NAME"
  3. ip-l2tp - L2TPv3 static unmanaged tunnel configuration
  4. .SH "SYNOPSIS"
  5. .sp
  6. .ad l
  7. .in +8
  8. .ti -8
  9. .B ip
  10. .RI "[ " OPTIONS " ]"
  11. .B l2tp
  12. .RI " { " COMMAND " | "
  13. .BR help " }"
  14. .sp
  15. .ti -8
  16. .BR "ip l2tp add tunnel"
  17. .br
  18. .BI remote " ADDR " local " ADDR "
  19. .br
  20. .B tunnel_id
  21. .IR ID
  22. .B peer_tunnel_id
  23. .IR ID
  24. .br
  25. .RB "[ " encap " { " ip " | " udp " } ]"
  26. .br
  27. .RB "[ " udp_sport
  28. .IR PORT
  29. .RB " ] [ " udp_dport
  30. .IR PORT
  31. .RB " ]"
  32. .br
  33. .RB "[ " udp_csum " { " on " | " off " } ]"
  34. .br
  35. .RB "[ " udp6_csum_tx " { " on " | " off " } ]"
  36. .br
  37. .RB "[ " udp6_csum_rx " { " on " | " off " } ]"
  38. .br
  39. .ti -8
  40. .BR "ip l2tp add session"
  41. .RB "[ " name
  42. .IR NAME
  43. .RB " ]"
  44. .br
  45. .B tunnel_id
  46. .IR ID
  47. .B session_id
  48. .IR ID
  49. .B peer_session_id
  50. .IR ID
  51. .br
  52. .RB "[ " cookie
  53. .IR HEXSTR
  54. .RB " ] [ " peer_cookie
  55. .IR HEXSTR
  56. .RB " ]"
  57. .br
  58. .RB "[ " l2spec_type " { " none " | " default " } ]"
  59. .br
  60. .RB "[ " seq " { " none " | " send " | " recv " | " both " } ]"
  61. .br
  62. .ti -8
  63. .BR "ip l2tp del tunnel"
  64. .B tunnel_id
  65. .IR ID
  66. .br
  67. .ti -8
  68. .BR "ip l2tp del session"
  69. .B tunnel_id
  70. .IR ID
  71. .B session_id
  72. .IR ID
  73. .br
  74. .ti -8
  75. .BR "ip l2tp show tunnel" " [ " tunnel_id
  76. .IR ID " ]"
  77. .br
  78. .ti -8
  79. .BR "ip l2tp show session" " [ " tunnel_id
  80. .IR ID .B " ] ["
  81. .B session_id
  82. .IR ID " ]"
  83. .br
  84. .ti -8
  85. .IR NAME " := "
  86. .IR STRING
  87. .ti -8
  88. .IR ADDR " := { " IP_ADDRESS " |"
  89. .BR any " }"
  90. .ti -8
  91. .IR PORT " := { " NUMBER " }"
  92. .ti -8
  93. .IR ID " := { " NUMBER " }"
  94. .ti -8
  95. .ti -8
  96. .IR HEXSTR " := { 8 or 16 hex digits (4 / 8 bytes) }"
  97. .SH DESCRIPTION
  98. The
  99. .B ip l2tp
  100. commands are used to establish static, or so-called
  101. .I unmanaged
  102. L2TPv3 ethernet tunnels. For unmanaged tunnels, there is no L2TP
  103. control protocol so no userspace daemon is required - tunnels are
  104. manually created by issuing commands at a local system and at a remote
  105. peer.
  106. .PP
  107. L2TPv3 is suitable for Layer-2 tunneling. Static tunnels are useful
  108. to establish network links across IP networks when the tunnels are
  109. fixed. L2TPv3 tunnels can carry data of more than one session. Each
  110. session is identified by a session_id and its parent tunnel's
  111. tunnel_id. A tunnel must be created before a session can be created in
  112. the tunnel.
  113. .PP
  114. When creating an L2TP tunnel, the IP address of the remote peer is
  115. specified, which can be either an IPv4 or IPv6 address. The local IP
  116. address to be used to reach the peer must also be specified. This is
  117. the address on which the local system will listen for and accept
  118. received L2TP data packets from the peer.
  119. .PP
  120. L2TPv3 defines two packet encapsulation formats: UDP or IP. UDP
  121. encapsulation is most common. IP encapsulation uses a dedicated IP
  122. protocol value to carry L2TP data without the overhead of UDP. Use IP
  123. encapsulation only when there are no NAT devices or firewalls in the
  124. network path.
  125. .PP
  126. When an L2TPv3 ethernet session is created, a virtual network
  127. interface is created for the session, which must then be configured
  128. and brought up, just like any other network interface. When data is
  129. passed through the interface, it is carried over the L2TP tunnel to
  130. the peer. By configuring the system's routing tables or adding the
  131. interface to a bridge, the L2TP interface is like a virtual wire
  132. (pseudowire) connected to the peer.
  133. .PP
  134. Establishing an unmanaged L2TPv3 ethernet pseudowire involves manually
  135. creating L2TP contexts on the local system and at the peer. Parameters
  136. used at each site must correspond or no data will be passed. No
  137. consistency checks are possible since there is no control protocol
  138. used to establish unmanaged L2TP tunnels. Once the virtual network
  139. interface of a given L2TP session is configured and enabled, data can
  140. be transmitted, even if the peer isn't yet configured. If the peer
  141. isn't configured, the L2TP data packets will be discarded by
  142. the peer.
  143. .PP
  144. To establish an unmanaged L2TP tunnel, use
  145. .B l2tp add tunnel
  146. and
  147. .B l2tp add session
  148. commands described in this document. Then configure and enable the
  149. tunnel's virtual network interface, as required.
  150. .PP
  151. Note that unmanaged tunnels carry only ethernet frames. If you need to
  152. carry PPP traffic (L2TPv2) or your peer doesn't support unmanaged
  153. L2TPv3 tunnels, you will need an L2TP server which implements the L2TP
  154. control protocol. The L2TP control protocol allows dynamic L2TP
  155. tunnels and sessions to be established and provides for detecting and
  156. acting upon network failures.
  157. .SS ip l2tp add tunnel - add a new tunnel
  158. .TP
  159. .BI tunnel_id " ID"
  160. set the tunnel id, which is a 32-bit integer value. Uniquely
  161. identifies the tunnel. The value used must match the peer_tunnel_id
  162. value being used at the peer.
  163. .TP
  164. .BI peer_tunnel_id " ID"
  165. set the peer tunnel id, which is a 32-bit integer value assigned to
  166. the tunnel by the peer. The value used must match the tunnel_id value
  167. being used at the peer.
  168. .TP
  169. .BI remote " ADDR"
  170. set the IP address of the remote peer. May be specified as an IPv4
  171. address or an IPv6 address.
  172. .TP
  173. .BI local " ADDR"
  174. set the IP address of the local interface to be used for the
  175. tunnel. This address must be the address of a local interface. May be
  176. specified as an IPv4 address or an IPv6 address.
  177. .TP
  178. .BI encap " ENCAP"
  179. set the encapsulation type of the tunnel.
  180. .br
  181. Valid values for encapsulation are:
  182. .BR udp ", " ip "."
  183. .TP
  184. .BI udp_sport " PORT"
  185. set the UDP source port to be used for the tunnel. Must be present
  186. when udp encapsulation is selected. Ignored when ip encapsulation is
  187. selected.
  188. .TP
  189. .BI udp_dport " PORT"
  190. set the UDP destination port to be used for the tunnel. Must be
  191. present when udp encapsulation is selected. Ignored when ip
  192. encapsulation is selected.
  193. .TP
  194. .BI udp_csum " STATE"
  195. (IPv4 only) control if IPv4 UDP checksums should be calculated and checked for the
  196. encapsulating UDP packets, when UDP encapsulating is selected.
  197. Default is
  198. .BR off "."
  199. .br
  200. Valid values are:
  201. .BR on ", " off "."
  202. .TP
  203. .BI udp6_csum_tx " STATE"
  204. (IPv6 only) control if IPv6 UDP checksums should be calculated for encapsulating
  205. UDP packets, when UDP encapsulating is selected.
  206. Default is
  207. .BR on "."
  208. .br
  209. Valid values are:
  210. .BR on ", " off "."
  211. .TP
  212. .BI udp6_csum_rx " STATE"
  213. (IPv6 only) control if IPv6 UDP checksums should be checked for the encapsulating
  214. UDP packets, when UDP encapsulating is selected.
  215. Default is
  216. .BR on "."
  217. .br
  218. Valid values are:
  219. .BR on ", " off "."
  220. .SS ip l2tp del tunnel - destroy a tunnel
  221. .TP
  222. .BI tunnel_id " ID"
  223. set the tunnel id of the tunnel to be deleted. All sessions within the
  224. tunnel must be deleted first.
  225. .SS ip l2tp show tunnel - show information about tunnels
  226. .TP
  227. .BI tunnel_id " ID"
  228. set the tunnel id of the tunnel to be shown. If not specified,
  229. information about all tunnels is printed.
  230. .SS ip l2tp add session - add a new session to a tunnel
  231. .TP
  232. .BI name " NAME "
  233. sets the session network interface name. Default is l2tpethN.
  234. .TP
  235. .BI tunnel_id " ID"
  236. set the tunnel id, which is a 32-bit integer value. Uniquely
  237. identifies the tunnel into which the session will be created. The
  238. tunnel must already exist.
  239. .TP
  240. .BI session_id " ID"
  241. set the session id, which is a 32-bit integer value. Uniquely
  242. identifies the session being created. The value used must match the
  243. peer_session_id value being used at the peer.
  244. .TP
  245. .BI peer_session_id " ID"
  246. set the peer session id, which is a 32-bit integer value assigned to
  247. the session by the peer. The value used must match the session_id
  248. value being used at the peer.
  249. .TP
  250. .BI cookie " HEXSTR"
  251. sets an optional cookie value to be assigned to the session. This is a
  252. 4 or 8 byte value, specified as 8 or 16 hex digits,
  253. e.g. 014d3636deadbeef. The value must match the peer_cookie value set
  254. at the peer. The cookie value is carried in L2TP data packets and is
  255. checked for expected value at the peer. Default is to use no cookie.
  256. .TP
  257. .BI peer_cookie " HEXSTR"
  258. sets an optional peer cookie value to be assigned to the session. This
  259. is a 4 or 8 byte value, specified as 8 or 16 hex digits,
  260. e.g. 014d3636deadbeef. The value must match the cookie value set at
  261. the peer. It tells the local system what cookie value to expect to
  262. find in received L2TP packets. Default is to use no cookie.
  263. .TP
  264. .BI l2spec_type " L2SPECTYPE"
  265. set the layer2specific header type of the session.
  266. .br
  267. Valid values are:
  268. .BR none ", " default "."
  269. .TP
  270. .BI seq " SEQ"
  271. controls sequence numbering to prevent or detect out of order packets.
  272. .B send
  273. puts a sequence number in the default layer2specific header of each
  274. outgoing packet.
  275. .B recv
  276. reorder packets if they are received out of order.
  277. Default is
  278. .BR none "."
  279. .br
  280. Valid values are:
  281. .BR none ", " send ", " recv ", " both "."
  282. .SS ip l2tp del session - destroy a session
  283. .TP
  284. .BI tunnel_id " ID"
  285. set the tunnel id in which the session to be deleted is located.
  286. .TP
  287. .BI session_id " ID"
  288. set the session id of the session to be deleted.
  289. .SS ip l2tp show session - show information about sessions
  290. .TP
  291. .BI tunnel_id " ID"
  292. set the tunnel id of the session(s) to be shown. If not specified,
  293. information about sessions in all tunnels is printed.
  294. .TP
  295. .BI session_id " ID"
  296. set the session id of the session to be shown. If not specified,
  297. information about all sessions is printed.
  298. .SH EXAMPLES
  299. .PP
  300. .SS Setup L2TP tunnels and sessions
  301. .nf
  302. site-A:# ip l2tp add tunnel tunnel_id 3000 peer_tunnel_id 4000 \\
  303. encap udp local 1.2.3.4 remote 5.6.7.8 \\
  304. udp_sport 5000 udp_dport 6000
  305. site-A:# ip l2tp add session tunnel_id 3000 session_id 1000 \\
  306. peer_session_id 2000
  307. site-B:# ip l2tp add tunnel tunnel_id 4000 peer_tunnel_id 3000 \\
  308. encap udp local 5.6.7.8 remote 1.2.3.4 \\
  309. udp_sport 6000 udp_dport 5000
  310. site-B:# ip l2tp add session tunnel_id 4000 session_id 2000 \\
  311. peer_session_id 1000
  312. site-A:# ip link set l2tpeth0 up mtu 1488
  313. site-B:# ip link set l2tpeth0 up mtu 1488
  314. .fi
  315. .PP
  316. Notice that the IP addresses, UDP ports and tunnel / session ids are
  317. matched and reversed at each site.
  318. .SS Configure as IP interfaces
  319. The two interfaces can be configured with IP addresses if only IP data
  320. is to be carried. This is perhaps the simplest configuration.
  321. .PP
  322. .nf
  323. site-A:# ip addr add 10.42.1.1 peer 10.42.1.2 dev l2tpeth0
  324. site-B:# ip addr add 10.42.1.2 peer 10.42.1.1 dev l2tpeth0
  325. site-A:# ping 10.42.1.2
  326. .fi
  327. .PP
  328. Now the link should be usable. Add static routes as needed to have
  329. data sent over the new link.
  330. .PP
  331. .SS Configure as bridged interfaces
  332. To carry non-IP data, the L2TP network interface is added to a bridge
  333. instead of being assigned its own IP address, using standard Linux
  334. utilities. Since raw ethernet frames are then carried inside the
  335. tunnel, the MTU of the L2TP interfaces must be set to allow space for
  336. those headers.
  337. .PP
  338. .nf
  339. site-A:# ip link set l2tpeth0 up mtu 1446
  340. site-A:# ip link add br0 type bridge
  341. site-A:# ip link set l2tpeth0 master br0
  342. site-A:# ip link set eth0 master br0
  343. site-A:# ip link set br0 up
  344. .fi
  345. .PP
  346. If you are using VLANs, setup a bridge per VLAN and bridge each VLAN
  347. over a separate L2TP session. For example, to bridge VLAN ID 5 on eth1
  348. over an L2TP pseudowire:
  349. .PP
  350. .nf
  351. site-A:# ip link set l2tpeth0 up mtu 1446
  352. site-A:# ip link add brvlan5 type bridge
  353. site-A:# ip link set l2tpeth0.5 master brvlan5
  354. site-A:# ip link set eth1.5 master brvlan5
  355. site-A:# ip link set brvlan5 up
  356. .fi
  357. .PP
  358. Adding the L2TP interface to a bridge causes the bridge to forward
  359. traffic over the L2TP pseudowire just like it forwards over any other
  360. interface. The bridge learns MAC addresses of hosts attached to each
  361. interface and intelligently forwards frames from one bridge port to
  362. another. IP addresses are not assigned to the l2tpethN interfaces. If
  363. the bridge is correctly configured at both sides of the L2TP
  364. pseudowire, it should be possible to reach hosts in the peer's bridged
  365. network.
  366. .PP
  367. When raw ethernet frames are bridged across an L2TP tunnel, large
  368. frames may be fragmented and forwarded as individual IP fragments to
  369. the recipient, depending on the MTU of the physical interface used by
  370. the tunnel. When the ethernet frames carry protocols which are
  371. reassembled by the recipient, like IP, this isn't a problem. However,
  372. such fragmentation can cause problems for protocols like PPPoE where
  373. the recipient expects to receive ethernet frames exactly as
  374. transmitted. In such cases, it is important that frames leaving the
  375. tunnel are reassembled back into a single frame before being
  376. forwarded on. To do so, enable netfilter connection tracking
  377. (conntrack) or manually load the Linux netfilter defrag modules at
  378. each tunnel endpoint.
  379. .PP
  380. .nf
  381. site-A:# modprobe nf_defrag_ipv4
  382. site-B:# modprobe nf_defrag_ipv4
  383. .fi
  384. .PP
  385. If L2TP is being used over IPv6, use the IPv6 defrag module.
  386. .SH INTEROPERABILITY
  387. .PP
  388. Unmanaged (static) L2TPv3 tunnels are supported by some network
  389. equipment vendors such as Cisco.
  390. .PP
  391. In Linux, L2TP Hello messages are not supported in unmanaged
  392. tunnels. Hello messages are used by L2TP clients and servers to detect
  393. link failures in order to automate tearing down and reestablishing
  394. dynamic tunnels. If a non-Linux peer supports Hello messages in
  395. unmanaged tunnels, it must be turned off to interoperate with Linux.
  396. .PP
  397. Linux defaults to use the Default Layer2SpecificHeader type as defined
  398. in the L2TPv3 protocol specification, RFC3931. This setting must be
  399. consistent with that configured at the peer. Some vendor
  400. implementations (e.g. Cisco) default to use a Layer2SpecificHeader
  401. type of None.
  402. .SH SEE ALSO
  403. .br
  404. .BR ip (8)
  405. .SH AUTHOR
  406. James Chapman <jchapman@katalix.com>