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
|
<table class="head">
<tr>
<td class="head-ltitle">ECN(9)</td>
<td class="head-vol">Kernel Developer's Manual</td>
<td class="head-rtitle">ECN(9)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">ecn</code>,
<code class="Nm">ip_ecn_ingress</code>,
<code class="Nm">ip_ecn_egress</code>,
<code class="Nm">ip6_ecn_ingress</code>,
<code class="Nm">ip6_ecn_egress</code> — <span class="Nd">IP ECN
interfaces for tunnel encapsulation/decapsulation</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">sys/netinet/ip_ecn.h</a>></code>
<br/>
<code class="In">#include
<<a class="In">sys/netinet6/ip6_ecn.h</a>></code></p>
<section class="Ss">
<h2 class="Ss" id="Constants"><a class="permalink" href="#Constants">Constants</a></h2>
<p class="Pp"><code class="Dv">ECN_COMPLETE</code>
<code class="Dv">ECN_ALLOWED</code> <code class="Dv">ECN_FORBIDDEN</code>
<code class="Dv">ECN_NOCARE</code></p>
</section>
<section class="Ss">
<h2 class="Ss" id="ECN_Manipulation_Functions"><a class="permalink" href="#ECN_Manipulation_Functions">ECN
Manipulation Functions</a></h2>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">ip_ecn_ingress</code>(<var class="Fa" style="white-space: nowrap;">int
mode</var>, <var class="Fa" style="white-space: nowrap;">uint8_t
*outer</var>, <var class="Fa" style="white-space: nowrap;">const uint8_t
*inner</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">ip6_ecn_ingress</code>(<var class="Fa" style="white-space: nowrap;">int
mode</var>, <var class="Fa" style="white-space: nowrap;">uint32_t
*outer</var>, <var class="Fa" style="white-space: nowrap;">const uint32_t
*inner</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">ip_ecn_egress</code>(<var class="Fa" style="white-space: nowrap;">int
mode</var>, <var class="Fa" style="white-space: nowrap;">uint8_t
*outer</var>, <var class="Fa" style="white-space: nowrap;">const uint8_t
*inner</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">ip6_ecn_egress</code>(<var class="Fa" style="white-space: nowrap;">int
mode</var>, <var class="Fa" style="white-space: nowrap;">uint32_t
*outer</var>, <var class="Fa" style="white-space: nowrap;">const uint32_t
*inner</var>);</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The
<a class="permalink" href="#ip_ecn_ingress"><code class="Fn" id="ip_ecn_ingress">ip_ecn_ingress</code></a>()
and <code class="Fn">ip_ecn_egress</code>() interfaces implement Explicit
Congestion Notification (ECN) processing for tunnel encapsulation (ingress)
and decapsulation (egress). They operate on the ECN bits in the IP Type of
Service (TOS) or IPv6 Traffic Class (TCLASS) header field. These functions
implements the standard specification of RFC6040 in
<var class="Vt">ECN_ALLOWED</var> mode for
<code class="Fn">ip_ecn_egress</code>() with addition of
<var class="Vt">ECN_FORBIDDEN</var> mode as compatibility mode in
<code class="Fn">ip_ecn_ingress</code>().</p>
<section class="Ss">
<h2 class="Ss" id="Interface"><a class="permalink" href="#Interface">Interface</a></h2>
<p class="Pp">The functions for manipulating <var class="Vt">ip_tos</var> and
<var class="Vt">ipv6_flow</var> are as follows:</p>
<div class="Bd-indent">
<dl class="Bl-tag">
<dt><code class="Fn">ip_ecn_ingress</code>()
<code class="Fn">ip6_ecn_ingress</code>()</dt>
<dd>Perform ECN processing at encapsulation time (ingress) based on the ECN
bits of the <var class="Vt">ip_tos</var> field in <var class="Vt">struct
ip</var> or the <var class="Vt">ip6_flow</var> field in
<var class="Vt">struct ip6_hdr</var> as <var class="Va">inner</var> to
<var class="Va">outer</var>. It also copies the DSCP value from
<var class="Va">inner</var> to <var class="Va">outer</var>.</dd>
<dt><code class="Fn">ip_ecn_egress</code>()
<code class="Fn">ip6_ecn_egress</code>()</dt>
<dd>Perform ECN processing at decapsulation time (egress) based on the ECN
bits of <var class="Va">outer</var> to <var class="Va">inner</var>.
<var class="Vt">ECN_ALLOWED</var> mode may modify the
<var class="Va">inner</var> ECN bits or instruct the caller to drop or log
by returning <var class="Vt">ECN_WARN</var> or
<var class="Vt">ECN_ALARM</var> values.</dd>
</dl>
</div>
<p class="Pp" id="ip_ecn_egress">Return codes for
<a class="permalink" href="#ip_ecn_egress"><code class="Fn">ip_ecn_egress</code></a>()
are as follows:</p>
<div class="Bd-indent">
<dl class="Bl-tag">
<dt id="ECN_DROP"><a class="permalink" href="#ECN_DROP"><code class="Dv">ECN_DROP</code></a></dt>
<dd>(0) Caller MUST drop the packet.</dd>
<dt id="ECN_SUCCESS"><a class="permalink" href="#ECN_SUCCESS"><code class="Dv">ECN_SUCCESS</code></a></dt>
<dd>(1) Processing succeeded; inner ECN bits may have been updated.</dd>
<dt id="ECN_WARN"><a class="permalink" href="#ECN_WARN"><code class="Dv">ECN_WARN</code></a></dt>
<dd>(2) Processing succeeded; caller MAY log a warning for an anomalous ECN
combination.</dd>
<dt id="ECN_ALARM"><a class="permalink" href="#ECN_ALARM"><code class="Dv">ECN_ALARM</code></a></dt>
<dd>(3) Processing succeeded; caller SHOULD log and MAY raise an alarm for a
serious ECN anomaly.</dd>
</dl>
</div>
<p class="Pp">The following modes are handled by functions:</p>
<div class="Bd-indent">
<dl class="Bl-tag">
<dt id="ECN_COMPLETE"><a class="permalink" href="#ECN_COMPLETE"><code class="Dv">ECN_COMPLETE</code></a></dt>
<dd>Normal mode as defined in RFC6040. ECN bits are preserved through
encapsulation; decapsulation follows RFC6040 rules and it returns
<var class="Vt">ECN_WARN</var> or <var class="Vt">ECN_ALARM</var> values
when a potentially dangerous packet detected.</dd>
<dt id="ECN_ALLOWED"><a class="permalink" href="#ECN_ALLOWED"><code class="Dv">ECN_ALLOWED</code></a></dt>
<dd>Normal mode as defined in RFC6040 without security checks. ECN bits are
preserved through encapsulation; decapsulation follows RFC6040 rules.</dd>
<dt id="ECN_FORBIDDEN"><a class="permalink" href="#ECN_FORBIDDEN"><code class="Dv">ECN_FORBIDDEN</code></a></dt>
<dd>Compatibility mode. ECN is stripped on encapsulation and decapsulation
will drop packets that carry CE in the outer header. This mode should not
be used in
<a class="permalink" href="#ip_ecn_egress~2"><code class="Fn" id="ip_ecn_egress~2">ip_ecn_egress</code></a>()
or
<a class="permalink" href="#ip6_ecn_egress"><code class="Fn" id="ip6_ecn_egress">ip6_ecn_egress</code></a>()
since the <var class="Vt">ECN_ALLOWED</var> mode already covers all
possible scenarios as specified in RFC6040.</dd>
<dt id="ECN_NOCARE"><a class="permalink" href="#ECN_NOCARE"><code class="Dv">ECN_NOCARE</code></a></dt>
<dd>leave ECN bits unchanged and ignored.</dd>
</dl>
</div>
</section>
<section class="Ss">
<h2 class="Ss" id="IPV6_HANDLING"><a class="permalink" href="#IPV6_HANDLING">IPV6
HANDLING</a></h2>
<p class="Pp">IPv6 interfaces
<a class="permalink" href="#ip6_ecn_ingress"><code class="Fn" id="ip6_ecn_ingress">ip6_ecn_ingress</code></a>()
and <code class="Fn">ip6_ecn_egress</code>() extract the 8-bit DSCP and ECN
values from the 32-bit <var class="Vt">ip6_flow</var> and insert it to IPv4
equivalent interfaces.</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">ip(4)</a>, <a class="Xr">ip6(4)</a>,
<a class="Xr">ipsec(4)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">Historically <code class="Fn">ip_ecn_egress</code>() used a
boolean-style return. The current API preserves numeric mapping for drop
(ECN_DROP == 0) and success (ECN_SUCCESS == 1) but defines additional
non-zero status codes (ECN_WARN, ECN_ALARM). Callers that only test for
non-zero success will continue to treat WARN/ALARM as success.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp"><span class="An">Pouria Mousavizadeh Tehrani</span>
<<a class="Mt" href="mailto:pouria@FreeBSD.org">pouria@FreeBSD.org</a>></p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">March 19, 2026</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
