From nobody Thu Mar 19 10:29:06 2026 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4fc2423jDdz6W7h9 for ; Thu, 19 Mar 2026 10:29:06 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R12" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4fc2422GDRz3fP8 for ; Thu, 19 Mar 2026 10:29:06 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1773916146; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=kn7XN7jObLKzcUkeCoaQXMMzsbWcV6DhSTU4Un8x24g=; b=XylbUd2J/H22zViiXzZzI+nSVhscc0aF5hh5ia+nWz050uEpN/4kmBzjf4JRwpxOtUuGw/ 7aaGmxLhQ3MOfykwvGmGHIv1hjLsTXAKXrC5oovD7aw7hDbzVMwnfiy0BsAduYAaw8Rkg8 Gb8Z6KqzHIvperGv2n68FQtUBWY4Pj8ymuiUkF+M5MyQjXcEYyVZDpj3lw7wr0N8D+nBCZ Cp2qCG/HpEWnIIIHQ8GXGNQ7DRTGak/fT4Cm5wG6cxa6mGkmUqkBDt9lYXrurDO1RAiiBL xBQaRAMj9uAsoClQJ/G9EJCuOOo2FV2M5aW4XUN1UUXi0iJc+2SpurCYCv1bAg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1773916146; a=rsa-sha256; cv=none; b=vwpk82bl/vhCyiTz+4yV8lYChaFVelLw3MjV9QJQBpxtt/ypEi3wdfmh+ezPFhyqDld+uJ EeQva58888KCwI7V0QypKPz4bnyvy7+8Rq7GJb6nivj35hSAjEMtcFRZHHEnZNF0rnCKzh 9SlEGTcsuwkVmxUkcuc+P5gGe+ENI/C9y9HeRLP/HezOg8IOiBPcKx7NK6LpZ8NmmHEB// cRhmKoeeIWmmfoQX4+qAdRh8FsF40mCgo+5dQ3abu2d5WPzEyY/ci2IKR8HoJc0lSjFy5C Ni8lrypLMpD2zPP9dsptCMRt0bCylscHzGJbBatskCKlYjPWfKcFaOj4Z9CjbA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1773916146; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=kn7XN7jObLKzcUkeCoaQXMMzsbWcV6DhSTU4Un8x24g=; b=Sw5xUqwNEazz3w9jSDcV7c9i9adP05mFZSu7O14WTvs9TdFXiju8haV5FbKvIrhopSk7tp bkaCz8ZsNl4bsGoTPSGMHm2YOWClEznk0X8LWwNFy/DaO1ucdEk/+pT9Abac+xqU2KmUgV UcQeCR4ht0g708U0LKsCK6kZbdxTChPQput+d8vF5pjRvIfV0RKUfg3zr8wZpkPCMlLlj3 cDxgJYRkXS4SeVTqIA5fs3iKDc6Ilz7uhJMDjYbCxRTA6Tb/j8pyKH75wHiU700+6OYAdI SG/bbPCFoHePbt1KswpNW/xy0enMhkjjmaTbih0ZmbQh4MyezjluLUB2VYnqRQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4fc2421LKYzr20 for ; Thu, 19 Mar 2026 10:29:06 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 20d5c by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Thu, 19 Mar 2026 10:29:06 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Pouria Mousavizadeh Tehrani Subject: git: ba4298b05564 - main - ecn.9: Add ecn(9) manual List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: pouria X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: ba4298b055642969d30389c5c92dd4d61a124fb6 Auto-Submitted: auto-generated Date: Thu, 19 Mar 2026 10:29:06 +0000 Message-Id: <69bbcff2.20d5c.3b3463aa@gitrepo.freebsd.org> The branch main has been updated by pouria: URL: https://cgit.FreeBSD.org/src/commit/?id=ba4298b055642969d30389c5c92dd4d61a124fb6 commit ba4298b055642969d30389c5c92dd4d61a124fb6 Author: Pouria Mousavizadeh Tehrani AuthorDate: 2026-03-19 10:25:53 +0000 Commit: Pouria Mousavizadeh Tehrani CommitDate: 2026-03-19 10:25:53 +0000 ecn.9: Add ecn(9) manual Add ecn manual for ip_ecn tunneling functions. Reviewed by: pauamma_gundo.com, tuexen Differential Revision: https://reviews.freebsd.org/D53517 --- share/man/man9/Makefile | 5 ++ share/man/man9/ecn.9 | 184 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 189 insertions(+) diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 8cc0add54f2e..31a3f886d0f3 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -144,6 +144,7 @@ MAN= accept_filter.9 \ drbr.9 \ driver.9 \ DRIVER_MODULE.9 \ + ecn.9 \ efirt.9 \ epoch.9 \ ether_gen_addr.9 \ @@ -1108,6 +1109,10 @@ MLINKS+=drbr.9 drbr_free.9 \ MLINKS+=DRIVER_MODULE.9 DRIVER_MODULE_ORDERED.9 \ DRIVER_MODULE.9 EARLY_DRIVER_MODULE.9 \ DRIVER_MODULE.9 EARLY_DRIVER_MODULE_ORDERED.9 +MLINKS+=ecn.9 ip_ecn_ingress.9 \ + ecn.9 ip_ecn_egress.9 \ + ecn.9 ip6_ecn_ingress.9 \ + ecn.9 ip6_ecn_egress.9 MLINKS+=epoch.9 epoch_context.9 \ epoch.9 epoch_alloc.9 \ epoch.9 epoch_free.9 \ diff --git a/share/man/man9/ecn.9 b/share/man/man9/ecn.9 new file mode 100644 index 000000000000..236385e74038 --- /dev/null +++ b/share/man/man9/ecn.9 @@ -0,0 +1,184 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2026 Pouria Mousavizadeh Tehrani +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 19, 2026 +.Dt ECN 9 +.Os +.Sh NAME +.Nm ecn , +.Nm ip_ecn_ingress , +.Nm ip_ecn_egress , +.Nm ip6_ecn_ingress , +.Nm ip6_ecn_egress +.Nd IP ECN interfaces for tunnel encapsulation/decapsulation +.Sh SYNOPSIS +.In sys/netinet/ip_ecn.h +.In sys/netinet6/ip6_ecn.h +.\" +.Ss "Constants" +.Dv ECN_COMPLETE +.Dv ECN_ALLOWED +.Dv ECN_FORBIDDEN +.Dv ECN_NOCARE +.\" +.Ss "ECN Manipulation Functions" +.Ft "void" +.Fn ip_ecn_ingress "int mode" "uint8_t *outer" "const uint8_t *inner" +.Ft "void" +.Fn "ip6_ecn_ingress" "int mode" "uint32_t *outer" "const uint32_t *inner" +.Ft "int" +.Fn "ip_ecn_egress" "int mode" "uint8_t *outer" "const uint8_t *inner" +.Ft "int" +.Fn "ip6_ecn_egress" "int mode" "uint32_t *outer" "const uint32_t *inner" +.\" +.Sh DESCRIPTION +The +.Fn ip_ecn_ingress +and +.Fn ip_ecn_egress +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 +.Vt ECN_ALLOWED +mode for +.Fn ip_ecn_egress +with addition of +.Vt ECN_FORBIDDEN +mode as compatibility mode in +.Fn ip_ecn_ingress . +.Ss Interface +The functions for manipulating +.Vt ip_tos +and +.Vt ipv6_flow +are as follows: +.Bl -tag -width indent -offset indent +.It Fn ip_ecn_ingress Fn ip6_ecn_ingress +Perform ECN processing at encapsulation time (ingress) based on +the ECN bits of the +.Vt ip_tos +field in +.Vt "struct ip" +or the +.Vt ip6_flow +field in +.Vt "struct ip6_hdr" +as +.Va inner +to +.Va outer . +It also copies the DSCP value from +.Va inner +to +.Va outer . +.It Fn ip_ecn_egress Fn ip6_ecn_egress +Perform ECN processing at decapsulation time (egress) based on +the ECN bits of +.Va outer +to +.Va inner . +.Vt ECN_ALLOWED +mode may modify the +.Va inner +ECN bits or instruct the caller to drop or log +by returning +.Vt ECN_WARN +or +.Vt ECN_ALARM +values. +.El +.Pp +Return codes for +.Fn ip_ecn_egress +are as follows: +.Bl -tag -width ".Dv ECN_SUCCESS" -offset indent +.It Dv ECN_DROP +(0) Caller MUST drop the packet. +.It Dv ECN_SUCCESS +(1) Processing succeeded; +inner ECN bits may have been updated. +.It Dv ECN_WARN +(2) Processing succeeded; +caller MAY log a warning for an anomalous ECN combination. +.It Dv ECN_ALARM +(3) Processing succeeded; +caller SHOULD log and MAY raise an alarm for a serious ECN anomaly. +.El +.Pp +The following modes are handled by functions: +.Bl -tag -width ".Dv ECN_FORBIDDEN" -offset indent +.It Dv ECN_COMPLETE +Normal mode as defined in RFC6040. +ECN bits are preserved through encapsulation; +decapsulation follows RFC6040 rules and it returns +.Vt ECN_WARN +or +.Vt ECN_ALARM +values when a potentially dangerous packet detected. +.It Dv ECN_ALLOWED +Normal mode as defined in RFC6040 without security checks. +ECN bits are preserved through encapsulation; +decapsulation follows RFC6040 rules. +.It Dv ECN_FORBIDDEN +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 +.Fn ip_ecn_egress +or +.Fn ip6_ecn_egress +since the +.Vt ECN_ALLOWED +mode already covers all possible scenarios as specified in RFC6040. +.It Dv ECN_NOCARE +leave ECN bits unchanged and ignored. +.El +.Ss IPV6 HANDLING +IPv6 interfaces +.Fn ip6_ecn_ingress +and +.Fn ip6_ecn_egress +extract the 8‑bit DSCP and ECN values from the 32‑bit +.Vt ip6_flow +and insert it to IPv4 equivalent interfaces. +.Sh SEE ALSO +.Xr ip 4 , +.Xr ip6 4 , +.Xr ipsec 4 +.Sh HISTORY +Historically +.Fn ip_ecn_egress +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. +.Sh AUTHORS +.An Pouria Mousavizadeh Tehrani Aq Mt pouria@FreeBSD.org