1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2026 Pouria Mousavizadeh Tehrani <pouria@FreeBSD.org> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd March 19, 2026 29.Dt ECN 9 30.Os 31.Sh NAME 32.Nm ecn , 33.Nm ip_ecn_ingress , 34.Nm ip_ecn_egress , 35.Nm ip6_ecn_ingress , 36.Nm ip6_ecn_egress 37.Nd IP ECN interfaces for tunnel encapsulation/decapsulation 38.Sh SYNOPSIS 39.In sys/netinet/ip_ecn.h 40.In sys/netinet6/ip6_ecn.h 41.\" 42.Ss "Constants" 43.Dv ECN_COMPLETE 44.Dv ECN_ALLOWED 45.Dv ECN_FORBIDDEN 46.Dv ECN_NOCARE 47.\" 48.Ss "ECN Manipulation Functions" 49.Ft "void" 50.Fn ip_ecn_ingress "int mode" "uint8_t *outer" "const uint8_t *inner" 51.Ft "void" 52.Fn "ip6_ecn_ingress" "int mode" "uint32_t *outer" "const uint32_t *inner" 53.Ft "int" 54.Fn "ip_ecn_egress" "int mode" "uint8_t *outer" "const uint8_t *inner" 55.Ft "int" 56.Fn "ip6_ecn_egress" "int mode" "uint32_t *outer" "const uint32_t *inner" 57.\" 58.Sh DESCRIPTION 59The 60.Fn ip_ecn_ingress 61and 62.Fn ip_ecn_egress 63interfaces implement Explicit Congestion Notification (ECN) processing for 64tunnel encapsulation (ingress) and decapsulation (egress). They operate on 65the ECN bits in the IP Type of Service (TOS) or 66IPv6 Traffic Class (TCLASS) header field. 67These functions implements the standard specification of RFC6040 in 68.Vt ECN_ALLOWED 69mode for 70.Fn ip_ecn_egress 71with addition of 72.Vt ECN_FORBIDDEN 73mode as compatibility mode in 74.Fn ip_ecn_ingress . 75.Ss Interface 76The functions for manipulating 77.Vt ip_tos 78and 79.Vt ipv6_flow 80are as follows: 81.Bl -tag -width indent -offset indent 82.It Fn ip_ecn_ingress Fn ip6_ecn_ingress 83Perform ECN processing at encapsulation time (ingress) based on 84the ECN bits of the 85.Vt ip_tos 86field in 87.Vt "struct ip" 88or the 89.Vt ip6_flow 90field in 91.Vt "struct ip6_hdr" 92as 93.Va inner 94to 95.Va outer . 96It also copies the DSCP value from 97.Va inner 98to 99.Va outer . 100.It Fn ip_ecn_egress Fn ip6_ecn_egress 101Perform ECN processing at decapsulation time (egress) based on 102the ECN bits of 103.Va outer 104to 105.Va inner . 106.Vt ECN_ALLOWED 107mode may modify the 108.Va inner 109ECN bits or instruct the caller to drop or log 110by returning 111.Vt ECN_WARN 112or 113.Vt ECN_ALARM 114values. 115.El 116.Pp 117Return codes for 118.Fn ip_ecn_egress 119are as follows: 120.Bl -tag -width ".Dv ECN_SUCCESS" -offset indent 121.It Dv ECN_DROP 122(0) Caller MUST drop the packet. 123.It Dv ECN_SUCCESS 124(1) Processing succeeded; 125inner ECN bits may have been updated. 126.It Dv ECN_WARN 127(2) Processing succeeded; 128caller MAY log a warning for an anomalous ECN combination. 129.It Dv ECN_ALARM 130(3) Processing succeeded; 131caller SHOULD log and MAY raise an alarm for a serious ECN anomaly. 132.El 133.Pp 134The following modes are handled by functions: 135.Bl -tag -width ".Dv ECN_FORBIDDEN" -offset indent 136.It Dv ECN_COMPLETE 137Normal mode as defined in RFC6040. 138ECN bits are preserved through encapsulation; 139decapsulation follows RFC6040 rules and it returns 140.Vt ECN_WARN 141or 142.Vt ECN_ALARM 143values when a potentially dangerous packet detected. 144.It Dv ECN_ALLOWED 145Normal mode as defined in RFC6040 without security checks. 146ECN bits are preserved through encapsulation; 147decapsulation follows RFC6040 rules. 148.It Dv ECN_FORBIDDEN 149Compatibility mode. 150ECN is stripped on encapsulation and decapsulation will 151drop packets that carry CE in the outer header. 152This mode should not be used in 153.Fn ip_ecn_egress 154or 155.Fn ip6_ecn_egress 156since the 157.Vt ECN_ALLOWED 158mode already covers all possible scenarios as specified in RFC6040. 159.It Dv ECN_NOCARE 160leave ECN bits unchanged and ignored. 161.El 162.Ss IPV6 HANDLING 163IPv6 interfaces 164.Fn ip6_ecn_ingress 165and 166.Fn ip6_ecn_egress 167extract the 8-bit DSCP and ECN values from the 32-bit 168.Vt ip6_flow 169and insert it to IPv4 equivalent interfaces. 170.Sh SEE ALSO 171.Xr ip 4 , 172.Xr ip6 4 , 173.Xr ipsec 4 174.Sh HISTORY 175Historically 176.Fn ip_ecn_egress 177used a boolean-style return. 178The current API preserves numeric mapping for drop (ECN_DROP == 0) 179and success (ECN_SUCCESS == 1) but defines additional non-zero 180status codes (ECN_WARN, ECN_ALARM). 181Callers that only test for non-zero success will continue to 182treat WARN/ALARM as success. 183.Sh AUTHORS 184.An Pouria Mousavizadeh Tehrani Aq Mt pouria@FreeBSD.org 185