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
This commit is contained in:
Pouria Mousavizadeh Tehrani
@@ -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 \
|
||||
|
||||
@@ -0,0 +1,184 @@
|
||||
.\"
|
||||
.\" SPDX-License-Identifier: BSD-2-Clause
|
||||
.\"
|
||||
.\" Copyright (c) 2026 Pouria Mousavizadeh Tehrani <pouria@FreeBSD.org>
|
||||
.\" 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
|
||||
Reference in New Issue
Block a user