Debian Codegraph @

upstream/debian-unstable/man8/ip-mptcp.8

raw
1 '\" t
2 .TH IP\-MPTCP 8 "4 Apr 2020" "iproute2" "Linux"
3 .SH "NAME"
4 ip-mptcp \- MPTCP path manager configuration
5 .SH "SYNOPSIS"
6 .ad l
7 .in +8
8 .ti -8
9 .B ip
10 .RI "[ " OPTIONS " ]"
11 .B mptcp
12 .RB "{ "
13 .B endpoint
14 .RB " | "
15 .B limits
16 .RB " | "
17 .B help
18 .RB " }"
19 .sp
20
21 .ti -8
22 .BR "ip mptcp endpoint add "
23 .IR IFADDR
24 .RB "[ " port
25 .IR PORT " ]"
26 .RB "[ " dev
27 .IR IFNAME " ]"
28 .RB "[ " id
29 .I ID
30 .RB "] [ "
31 .I FLAG-LIST
32 .RB "] "
33
34 .ti -8
35 .BR "ip mptcp endpoint delete id "
36 .I ID
37 .RB "[ "
38 .I IFADDR
39 .RB "] "
40
41 .ti -8
42 .BR "ip mptcp endpoint change "
43 .RB "[ " id
44 .I ID
45 .RB "] [ "
46 .IR IFADDR
47 .RB "] [ " port
48 .IR PORT " ]"
49 .RB "CHANGE-OPT"
50
51 .ti -8
52 .BR "ip mptcp endpoint show "
53 .RB "[ " id
54 .I ID
55 .RB "]"
56
57 .ti -8
58 .BR "ip mptcp endpoint flush"
59
60 .ti -8
61 .IR FLAG-LIST " := [ " FLAG-LIST " ] " FLAG
62
63 .ti -8
64 .IR FLAG " := ["
65 .B signal
66 .RB "|"
67 .B subflow
68 .RB "|"
69 .B laminar
70 .RB "|"
71 .B backup
72 .RB "|"
73 .B fullmesh
74 .RB "]"
75
76 .ti -8
77 .IR CHANGE-OPT " := ["
78 .B backup
79 .RB "|"
80 .B nobackup
81 .RB "|"
82 .B fullmesh
83 .RB "|"
84 .B nofullmesh
85 .RB "]"
86
87 .ti -8
88 .BR "ip mptcp limits set "
89 .RB "[ "
90 .B subflow
91 .IR SUBFLOW_NR " ]"
92 .RB "[ "
93 .B add_addr_accepted
94 .IR ADD_ADDR_ACCEPTED_NR " ]"
95
96 .ti -8
97 .BR "ip mptcp limits show"
98
99 .ti -8
100 .BR "ip mptcp monitor"
101
102 .SH DESCRIPTION
103
104 MPTCP is a transport protocol built on top of TCP that allows TCP
105 connections to use multiple paths to maximize resource usage and increase
106 redundancy. The ip-mptcp sub-commands allow configuring several aspects of the
107 MPTCP path manager, which is in charge of subflows creation:
108
109 .P
110 The
111 .B endpoint
112 object specifies the IP addresses that will be used and/or announced for
113 additional subflows:
114
115 .TS
116 l l.
117 ip mptcp endpoint add add new MPTCP endpoint
118 ip mptcp endpoint delete delete existing MPTCP endpoint
119 ip mptcp endpoint show get existing MPTCP endpoint
120 ip mptcp endpoint flush flush all existing MPTCP endpoints
121 .TE
122
123 .TP
124 .IR IFADDR
125 An IPv4 or IPv6 address. When used with the
126 .B delete id
127 operation, an
128 .B IFADDR
129 is only included when the
130 .B ID
131 is 0.
132
133 .TP
134 .IR PORT
135 When a port number is specified, incoming MPTCP subflows for already
136 established MPTCP sockets will be accepted on the specified port, regardless
137 the original listener port accepting the first MPTCP subflow and/or
138 this peer being actually on the client side. This option has to be used in
139 combination with the
140 .BR signal
141 flag.
142
143 .TP
144 .IR IFNAME
145 is the network interface name attached to the endpoint. It is important to
146 specify this device name linked to the address to make sure the system knows how
147 to route packets from the specified IP address to the correct network interface.
148 Without this, it might be required to add IP rules and routes to have the
149 expected behavior.
150
151 .TP
152 .IR ID
153 is a unique numeric identifier, between 0 and 255, for the given endpoint. It is
154 not possible to add endpoints with ID 0, because this special ID is reserved for
155 the initial subflow. For rules linked to the initial subflow, the path-manager
156 will look at endpoints matching the same address, and port if set, ignoring the
157 ID.
158
159 .TP
160 .BR signal
161 The endpoint will be announced/signalled to each peer via an MPTCP ADD_ADDR
162 sub-option. Typically, a server would be responsible for this. Upon reception of
163 an ADD_ADDR sub-option, the other peer, typically the client side, can try to
164 create additional subflows, see
165 .BR ADD_ADDR_ACCEPTED_NR.
166
167 .TP
168 .BR subflow
169 If additional subflow creation is allowed by the MPTCP limits, the MPTCP
170 path manager will try to create an additional subflow using this endpoint
171 as the source address after the MPTCP connection is established. A client would
172 typically do this.
173
174 .TP
175 .BR laminar
176 The endpoint will be used to create new subflows from the associated address to
177 additional addresses announced by the other peer. This will be done if allowed
178 by the MPTCP limits, and if the associated address is not already being used by
179 another subflow from the same MPTCP connection. Note that the
180 .BR fullmesh
181 flag takes precedence over the
182 .BR laminar
183 one. Without any of these two flags, the path-manager will create new subflows
184 to additional addresses announced by the other peer by selecting the source
185 address from the routing tables, which is harder to configure if the announced
186 address is not known in advance.
187
188 .TP
189 .BR backup
190 If this is a
191 .BR subflow
192 endpoint, the subflows created using this endpoint will have the backup
193 flag set during the connection process. This flag instructs the remote
194 peer to only send data on a given subflow when all non-backup subflows
195 are unavailable. When using the default packet scheduler with a 'backup'
196 endpoint, outgoing data from the local peer is also affected: packets
197 will only be sent from this endpoint when all non-backup subflows are
198 unavailable.
199
200 .TP
201 .BR fullmesh
202 If this is a
203 .BR subflow
204 endpoint and additional subflow creation is allowed by the MPTCP limits,
205 the MPTCP path manager will try to create an additional subflow for each
206 known peer address, using this endpoint as the source address. This will
207 occur after the MPTCP connection is established. If the peer did not
208 announce any additional addresses using the MPTCP ADD_ADDR sub-option,
209 this will behave the same as a plain
210 .BR subflow
211 endpoint. When the peer does announce addresses, each received ADD_ADDR
212 sub-option will trigger creation of an additional subflow to generate a
213 full mesh topology. This
214 .BR fullmesh
215 flag should always be used in combination with the
216 .BR subflow
217 one to be useful, except for the address used by the initial subflow,
218 where
219 .BR subflow
220 is then optional.
221
222 .TP
223 .BR implicit
224 In some scenarios, an MPTCP
225 .BR subflow
226 can use a local address mapped by an implicit endpoint created by the
227 in-kernel path manager. Once set, the implicit flag cannot be removed, but
228 other flags can be added to the endpoint. Implicit endpoints cannot be
229 created from user-space.
230
231 .sp
232 .PP
233 The
234 .B limits
235 object specifies the constraints for subflow creations:
236
237 .TS
238 l l.
239 ip mptcp limits show get current MPTCP subflow creation limits
240 ip mptcp limits set change the MPTCP subflow creation limits
241 .TE
242
243 .TP
244 .IR SUBFLOW_NR
245 specifies the maximum number of additional subflows allowed for each MPTCP
246 connection. Additional subflows can be created due to: incoming accepted
247 ADD_ADDR sub-option, local
248 .BR subflow
249 endpoints, additional subflows started by the peer.
250
251 .TP
252 .IR ADD_ADDR_ACCEPTED_NR
253 specifies the maximum number of incoming ADD_ADDR sub-options accepted for
254 each MPTCP connection. After receiving the specified number of ADD_ADDR
255 sub-options, any other incoming one will be ignored for the MPTCP connection
256 lifetime. When an ADD_ADDR sub-option is accepted and there are no local
257 .IR fullmesh
258 endpoints, the MPTCP path manager will try to create a new subflow using the
259 address in the ADD_ADDR sub-option as the destination address and a source
260 address determined using local routing resolution
261 When
262 .IR fullmesh
263 endpoints are available, the MPTCP path manager will try to create new subflows
264 using each
265 .IR fullmesh
266 endpoint as a source address and the peer's ADD_ADDR address as the destination.
267 In both cases the
268 .IR SUBFLOW_NR
269 limit is enforced.
270
271 .sp
272 .PP
273 .B monitor
274 displays creation and deletion of MPTCP connections as well as addition or removal of remote addresses and subflows.
275
276 .SH AUTHOR
277 Original Manpage by Paolo Abeni <[email protected]>