blob: d718bc2ff1cfc4e1e8d54d3002657dd8400086e3 [file] [log] [blame]
Ian McDonald98069ff2005-11-10 13:04:33 -08001DCCP protocol
Gerrit Renker4886fca2010-08-29 19:23:13 +00002=============
Ian McDonald98069ff2005-11-10 13:04:33 -08003
Ian McDonald98069ff2005-11-10 13:04:33 -08004
5Contents
6========
Ian McDonald98069ff2005-11-10 13:04:33 -08007- Introduction
8- Missing features
9- Socket options
Gerrit Renker4886fca2010-08-29 19:23:13 +000010- Sysctl variables
11- IOCTLs
12- Other tunables
Ian McDonald98069ff2005-11-10 13:04:33 -080013- Notes
14
Gerrit Renker4886fca2010-08-29 19:23:13 +000015
Ian McDonald98069ff2005-11-10 13:04:33 -080016Introduction
17============
Ian McDonald98069ff2005-11-10 13:04:33 -080018Datagram Congestion Control Protocol (DCCP) is an unreliable, connection
Gerrit Renkere333b3e2007-11-21 10:09:56 -020019oriented protocol designed to solve issues present in UDP and TCP, particularly
20for real-time and multimedia (streaming) traffic.
21It divides into a base protocol (RFC 4340) and plugable congestion control
22modules called CCIDs. Like plugable TCP congestion control, at least one CCID
23needs to be enabled in order for the protocol to function properly. In the Linux
24implementation, this is the TCP-like CCID2 (RFC 4341). Additional CCIDs, such as
25the TCP-friendly CCID3 (RFC 4342), are optional.
26For a brief introduction to CCIDs and suggestions for choosing a CCID to match
27given applications, see section 10 of RFC 4340.
Ian McDonald98069ff2005-11-10 13:04:33 -080028
29It has a base protocol and pluggable congestion control IDs (CCIDs).
30
Gerrit Renkerebe6f7e2007-11-21 10:00:17 -020031DCCP is a Proposed Standard (RFC 2026), and the homepage for DCCP as a protocol
32is at http://www.ietf.org/html.charters/dccp-charter.html
Ian McDonald98069ff2005-11-10 13:04:33 -080033
Gerrit Renker4886fca2010-08-29 19:23:13 +000034
Ian McDonald98069ff2005-11-10 13:04:33 -080035Missing features
36================
Gerrit Renkerebe6f7e2007-11-21 10:00:17 -020037The Linux DCCP implementation does not currently support all the features that are
38specified in RFCs 4340...42.
Ian McDonald98069ff2005-11-10 13:04:33 -080039
Ian McDonaldddfe10b2006-11-20 18:42:45 -020040The known bugs are at:
Michael Wittenc996d8b2010-11-15 19:55:34 +000041 http://www.linuxfoundation.org/collaborate/workgroups/networking/todo#DCCP
Ian McDonald98069ff2005-11-10 13:04:33 -080042
Gerrit Renkerebe6f7e2007-11-21 10:00:17 -020043For more up-to-date versions of the DCCP implementation, please consider using
44the experimental DCCP test tree; instructions for checking this out are on:
Michael Wittenc996d8b2010-11-15 19:55:34 +000045http://www.linuxfoundation.org/collaborate/workgroups/networking/dccp_testing#Experimental_DCCP_source_tree
Gerrit Renkerebe6f7e2007-11-21 10:00:17 -020046
47
Ian McDonald98069ff2005-11-10 13:04:33 -080048Socket options
49==============
Tomasz Grobelny871a2c12010-12-04 13:38:01 +010050DCCP_SOCKOPT_QPOLICY_ID sets the dequeuing policy for outgoing packets. It takes
51a policy ID as argument and can only be set before the connection (i.e. changes
52during an established connection are not supported). Currently, two policies are
53defined: the "simple" policy (DCCPQ_POLICY_SIMPLE), which does nothing special,
54and a priority-based variant (DCCPQ_POLICY_PRIO). The latter allows to pass an
55u32 priority value as ancillary data to sendmsg(), where higher numbers indicate
56a higher packet priority (similar to SO_PRIORITY). This ancillary data needs to
57be formatted using a cmsg(3) message header filled in as follows:
58 cmsg->cmsg_level = SOL_DCCP;
59 cmsg->cmsg_type = DCCP_SCM_PRIORITY;
60 cmsg->cmsg_len = CMSG_LEN(sizeof(uint32_t)); /* or CMSG_LEN(4) */
61
62DCCP_SOCKOPT_QPOLICY_TXQLEN sets the maximum length of the output queue. A zero
63value is always interpreted as unbounded queue length. If different from zero,
64the interpretation of this parameter depends on the current dequeuing policy
65(see above): the "simple" policy will enforce a fixed queue size by returning
66EAGAIN, whereas the "prio" policy enforces a fixed queue length by dropping the
67lowest-priority packet first. The default value for this parameter is
68initialised from /proc/sys/net/dccp/default/tx_qlen.
69
Gerrit Renker00e4d112006-09-22 09:33:58 +010070DCCP_SOCKOPT_SERVICE sets the service. The specification mandates use of
71service codes (RFC 4340, sec. 8.1.2); if this socket option is not set,
72the socket will fall back to 0 (which means that no meaningful service code
Gerrit Renker126acd52007-10-04 14:40:22 -070073is present). On active sockets this is set before connect(); specifying more
74than one code has no effect (all subsequent service codes are ignored). The
75case is different for passive sockets, where multiple service codes (up to 32)
76can be set before calling bind().
Ian McDonald98069ff2005-11-10 13:04:33 -080077
Gerrit Renker7c559a92007-10-04 14:39:22 -070078DCCP_SOCKOPT_GET_CUR_MPS is read-only and retrieves the current maximum packet
79size (application payload size) in bytes, see RFC 4340, section 14.
80
Gerrit Renkerd90ebcb2008-11-12 00:47:26 -080081DCCP_SOCKOPT_AVAILABLE_CCIDS is also read-only and returns the list of CCIDs
Gerrit Renker69a6a0b2010-02-07 20:20:28 +000082supported by the endpoint. The option value is an array of type uint8_t whose
83size is passed as option length. The minimum array size is 4 elements, the
84value returned in the optlen argument always reflects the true number of
85built-in CCIDs.
Gerrit Renkerd90ebcb2008-11-12 00:47:26 -080086
Gerrit Renkerb20a9c22008-11-23 16:02:31 -080087DCCP_SOCKOPT_CCID is write-only and sets both the TX and RX CCIDs at the same
88time, combining the operation of the next two socket options. This option is
89preferrable over the latter two, since often applications will use the same
90type of CCID for both directions; and mixed use of CCIDs is not currently well
91understood. This socket option takes as argument at least one uint8_t value, or
92an array of uint8_t values, which must match available CCIDS (see above). CCIDs
93must be registered on the socket before calling connect() or listen().
94
95DCCP_SOCKOPT_TX_CCID is read/write. It returns the current CCID (if set) or sets
96the preference list for the TX CCID, using the same format as DCCP_SOCKOPT_CCID.
97Please note that the getsockopt argument type here is `int', not uint8_t.
98
99DCCP_SOCKOPT_RX_CCID is analogous to DCCP_SOCKOPT_TX_CCID, but for the RX CCID.
100
Gerrit Renkerb8599d22007-12-13 12:25:01 -0200101DCCP_SOCKOPT_SERVER_TIMEWAIT enables the server (listening socket) to hold
102timewait state when closing the connection (RFC 4340, 8.3). The usual case is
103that the closing server sends a CloseReq, whereupon the client holds timewait
104state. When this boolean socket option is on, the server sends a Close instead
105and will enter TIMEWAIT. This option must be set after accept() returns.
106
Gerrit Renker6f4e5ff2006-11-10 17:43:06 -0200107DCCP_SOCKOPT_SEND_CSCOV and DCCP_SOCKOPT_RECV_CSCOV are used for setting the
108partial checksum coverage (RFC 4340, sec. 9.2). The default is that checksums
109always cover the entire packet and that only fully covered application data is
110accepted by the receiver. Hence, when using this feature on the sender, it must
111be enabled at the receiver, too with suitable choice of CsCov.
112
113DCCP_SOCKOPT_SEND_CSCOV sets the sender checksum coverage. Values in the
114 range 0..15 are acceptable. The default setting is 0 (full coverage),
115 values between 1..15 indicate partial coverage.
Gerrit Renker2bfd7542007-10-04 14:50:57 -0700116DCCP_SOCKOPT_RECV_CSCOV is for the receiver and has a different meaning: it
Gerrit Renker6f4e5ff2006-11-10 17:43:06 -0200117 sets a threshold, where again values 0..15 are acceptable. The default
118 of 0 means that all packets with a partial coverage will be discarded.
119 Values in the range 1..15 indicate that packets with minimally such a
120 coverage value are also acceptable. The higher the number, the more
Gerrit Renker2bfd7542007-10-04 14:50:57 -0700121 restrictive this setting (see [RFC 4340, sec. 9.2.1]). Partial coverage
122 settings are inherited to the child socket after accept().
Gerrit Renker6f4e5ff2006-11-10 17:43:06 -0200123
Gerrit Renkerf2645102007-03-20 15:01:14 -0300124The following two options apply to CCID 3 exclusively and are getsockopt()-only.
125In either case, a TFRC info struct (defined in <linux/tfrc.h>) is returned.
126DCCP_SOCKOPT_CCID_RX_INFO
127 Returns a `struct tfrc_rx_info' in optval; the buffer for optval and
128 optlen must be set to at least sizeof(struct tfrc_rx_info).
129DCCP_SOCKOPT_CCID_TX_INFO
130 Returns a `struct tfrc_tx_info' in optval; the buffer for optval and
131 optlen must be set to at least sizeof(struct tfrc_tx_info).
132
Gerrit Renker8e8c71f2007-11-21 09:56:48 -0200133On unidirectional connections it is useful to close the unused half-connection
134via shutdown (SHUT_WR or SHUT_RD): this will reduce per-packet processing costs.
Gerrit Renkerf2645102007-03-20 15:01:14 -0300135
Gerrit Renker4886fca2010-08-29 19:23:13 +0000136
Gerrit Renker2e2e9e92006-11-13 13:23:52 -0200137Sysctl variables
138================
139Several DCCP default parameters can be managed by the following sysctls
140(sysctl net.dccp.default or /proc/sys/net/dccp/default):
141
142request_retries
143 The number of active connection initiation retries (the number of
144 Requests minus one) before timing out. In addition, it also governs
145 the behaviour of the other, passive side: this variable also sets
146 the number of times DCCP repeats sending a Response when the initial
147 handshake does not progress from RESPOND to OPEN (i.e. when no Ack
148 is received after the initial Request). This value should be greater
149 than 0, suggested is less than 10. Analogue of tcp_syn_retries.
150
151retries1
152 How often a DCCP Response is retransmitted until the listening DCCP
153 side considers its connecting peer dead. Analogue of tcp_retries1.
154
155retries2
156 The number of times a general DCCP packet is retransmitted. This has
157 importance for retransmitted acknowledgments and feature negotiation,
158 data packets are never retransmitted. Analogue of tcp_retries2.
159
Gerrit Renker2e2e9e92006-11-13 13:23:52 -0200160tx_ccid = 2
Gerrit Renker0049bab2008-12-08 01:18:05 -0800161 Default CCID for the sender-receiver half-connection. Depending on the
162 choice of CCID, the Send Ack Vector feature is enabled automatically.
Gerrit Renker2e2e9e92006-11-13 13:23:52 -0200163
164rx_ccid = 2
Gerrit Renker0049bab2008-12-08 01:18:05 -0800165 Default CCID for the receiver-sender half-connection; see tx_ccid.
Gerrit Renker2e2e9e92006-11-13 13:23:52 -0200166
167seq_window = 100
Gerrit Renker792b4872009-01-16 23:36:31 +0000168 The initial sequence window (sec. 7.5.2) of the sender. This influences
169 the local ackno validity and the remote seqno validity windows (7.5.1).
Gerrit Renkerbfbb2342011-01-02 18:15:58 +0100170 Values in the range Wmin = 32 (RFC 4340, 7.5.2) up to 2^32-1 can be set.
Gerrit Renker2e2e9e92006-11-13 13:23:52 -0200171
Ian McDonald82e3ab92006-11-20 19:19:32 -0200172tx_qlen = 5
173 The size of the transmit buffer in packets. A value of 0 corresponds
174 to an unbounded transmit buffer.
175
Gerrit Renkera94f0f92007-09-26 11:31:49 -0300176sync_ratelimit = 125 ms
177 The timeout between subsequent DCCP-Sync packets sent in response to
178 sequence-invalid packets on the same socket (RFC 4340, 7.5.4). The unit
179 of this parameter is milliseconds; a value of 0 disables rate-limiting.
180
Gerrit Renker4886fca2010-08-29 19:23:13 +0000181
Gerrit Renkerc2814902007-11-21 10:14:31 -0200182IOCTLS
183======
184FIONREAD
185 Works as in udp(7): returns in the `int' argument pointer the size of
186 the next pending datagram in bytes, or 0 when no datagram is pending.
187
Gerrit Renker4886fca2010-08-29 19:23:13 +0000188
189Other tunables
190==============
191Per-route rto_min support
192 CCID-2 supports the RTAX_RTO_MIN per-route setting for the minimum value
193 of the RTO timer. This setting can be modified via the 'rto_min' option
194 of iproute2; for example:
195 > ip route change 10.0.0.0/24 rto_min 250j dev wlan0
196 > ip route add 10.0.0.254/32 rto_min 800j dev wlan0
197 > ip route show dev wlan0
Gerrit Renker89858ad2010-08-29 19:23:14 +0000198 CCID-3 also supports the rto_min setting: it is used to define the lower
199 bound for the expiry of the nofeedback timer. This can be useful on LANs
200 with very low RTTs (e.g., loopback, Gbit ethernet).
Gerrit Renker4886fca2010-08-29 19:23:13 +0000201
202
Ian McDonald98069ff2005-11-10 13:04:33 -0800203Notes
204=====
Ian McDonaldddfe10b2006-11-20 18:42:45 -0200205DCCP does not travel through NAT successfully at present on many boxes. This is
Gerrit Renker126acd52007-10-04 14:40:22 -0700206because the checksum covers the pseudo-header as per TCP and UDP. Linux NAT
Ian McDonaldddfe10b2006-11-20 18:42:45 -0200207support for DCCP has been added.