Debian Codegraph @

upstream/debian-trixie/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 backup
70 .RB "|"
71 .B fullmesh
72 .RB "]"
73
74 .ti -8
75 .IR CHANGE-OPT " := ["
76 .B backup
77 .RB "|"
78 .B nobackup
79 .RB "|"
80 .B fullmesh
81 .RB "|"
82 .B nofullmesh
83 .RB "]"
84
85 .ti -8
86 .BR "ip mptcp limits set "
87 .RB "[ "
88 .B subflow
89 .IR SUBFLOW_NR " ]"
90 .RB "[ "
91 .B add_addr_accepted
92 .IR ADD_ADDR_ACCEPTED_NR " ]"
93
94 .ti -8
95 .BR "ip mptcp limits show"
96
97 .ti -8
98 .BR "ip mptcp monitor"
99
100 .SH DESCRIPTION
101
102 MPTCP is a transport protocol built on top of TCP that allows TCP
103 connections to use multiple paths to maximize resource usage and increase
104 redundancy. The ip-mptcp sub-commands allow configuring several aspects of the
105 MPTCP path manager, which is in charge of subflows creation:
106
107 .P
108 The
109 .B endpoint
110 object specifies the IP addresses that will be used and/or announced for
111 additional subflows:
112
113 .TS
114 l l.
115 ip mptcp endpoint add add new MPTCP endpoint
116 ip mptcp endpoint delete delete existing MPTCP endpoint
117 ip mptcp endpoint show get existing MPTCP endpoint
118 ip mptcp endpoint flush flush all existing MPTCP endpoints
119 .TE
120
121 .TP
122 .IR IFADDR
123 An IPv4 or IPv6 address. When used with the
124 .B delete id
125 operation, an
126 .B IFADDR
127 is only included when the
128 .B ID
129 is 0.
130
131 .TP
132 .IR PORT
133 When a port number is specified, incoming MPTCP subflows for already
134 established MPTCP sockets will be accepted on the specified port, regardless
135 the original listener port accepting the first MPTCP subflow and/or
136 this peer being actually on the client side. This option has to be used in
137 combination with the
138 .BR signal
139 flag.
140
141 .TP
142 .IR IFNAME
143 is the network interface name attached to the endpoint. It is important to
144 specify this device name linked to the address to make sure the system knows how
145 to route packets from the specified IP address to the correct network interface.
146 Without this, it might be required to add IP rules and routes to have the
147 expected behavior.
148
149 .TP
150 .IR ID
151 is a unique numeric identifier, between 0 and 255, for the given endpoint. It is
152 not possible to add endpoints with ID 0, because this special ID is reserved for
153 the initial subflow. For rules linked to the initial subflow, the path-manager
154 will look at endpoints matching the same address, and port if set, ignoring the
155 ID.
156
157 .TP
158 .BR signal
159 The endpoint will be announced/signaled to each peer via an MPTCP ADD_ADDR
160 sub-option. Typically, a server would be responsible for this. Upon reception of
161 an ADD_ADDR sub-option, the other peer, typically the client side, can try to
162 create additional subflows, see
163 .BR ADD_ADDR_ACCEPTED_NR.
164
165 .TP
166 .BR subflow
167 If additional subflow creation is allowed by the MPTCP limits, the MPTCP
168 path manager will try to create an additional subflow using this endpoint
169 as the source address after the MPTCP connection is established. A client would
170 typically do this.
171
172 .TP
173 .BR backup
174 If this is a
175 .BR subflow
176 endpoint, the subflows created using this endpoint will have the backup
177 flag set during the connection process. This flag instructs the remote
178 peer to only send data on a given subflow when all non-backup subflows
179 are unavailable. When using the default packet scheduler with a 'backup'
180 endpoint, outgoing data from the local peer is also affected: packets
181 will only be sent from this endpoint when all non-backup subflows are
182 unavailable.
183
184 .TP
185 .BR fullmesh
186 If this is a
187 .BR subflow
188 endpoint and additional subflow creation is allowed by the MPTCP limits,
189 the MPTCP path manager will try to create an additional subflow for each
190 known peer address, using this endpoint as the source address. This will
191 occur after the MPTCP connection is established. If the peer did not
192 announce any additional addresses using the MPTCP ADD_ADDR sub-option,
193 this will behave the same as a plain
194 .BR subflow
195 endpoint. When the peer does announce addresses, each received ADD_ADDR
196 sub-option will trigger creation of an additional subflow to generate a
197 full mesh topology. This
198 .BR fullmesh
199 flag should always be used in combination with the
200 .BR subflow
201 one to be useful, except for the address used by the initial subflow,
202 where
203 .BR subflow
204 is then optional.
205
206 .TP
207 .BR implicit
208 In some scenarios, an MPTCP
209 .BR subflow
210 can use a local address mapped by a implicit endpoint created by the
211 in-kernel path manager. Once set, the implicit flag cannot be removed, but
212 other flags can be added to the endpoint. Implicit endpoints cannot be
213 created from user-space.
214
215 .sp
216 .PP
217 The
218 .B limits
219 object specifies the constraints for subflow creations:
220
221 .TS
222 l l.
223 ip mptcp limits show get current MPTCP subflow creation limits
224 ip mptcp limits set change the MPTCP subflow creation limits
225 .TE
226
227 .TP
228 .IR SUBFLOW_NR
229 specifies the maximum number of additional subflows allowed for each MPTCP
230 connection. Additional subflows can be created due to: incoming accepted
231 ADD_ADDR sub-option, local
232 .BR subflow
233 endpoints, additional subflows started by the peer.
234
235 .TP
236 .IR ADD_ADDR_ACCEPTED_NR
237 specifies the maximum number of incoming ADD_ADDR sub-options accepted for
238 each MPTCP connection. After receiving the specified number of ADD_ADDR
239 sub-options, any other incoming one will be ignored for the MPTCP connection
240 lifetime. When an ADD_ADDR sub-option is accepted and there are no local
241 .IR fullmesh
242 endpoints, the MPTCP path manager will try to create a new subflow using the
243 address in the ADD_ADDR sub-option as the destination address and a source
244 address determined using local routing resolution
245 When
246 .IR fullmesh
247 endpoints are available, the MPTCP path manager will try to create new subflows
248 using each
249 .IR fullmesh
250 endpoint as a source address and the peer's ADD_ADDR address as the destination.
251 In both cases the
252 .IR SUBFLOW_NR
253 limit is enforced.
254
255 .sp
256 .PP
257 .B monitor
258 displays creation and deletion of MPTCP connections as well as addition or removal of remote addresses and subflows.
259
260 .SH AUTHOR
261 Original Manpage by Paolo Abeni <[email protected]>